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About This Manual 


This manual is the latest release of the PlayStation® Library Reference as of Run-Time Library release 4.7. 
The purpose of this manual is to define all available PlayStation run-time library functions, macros and 

structures. The companion Run-Time Library Overview volume describes the structure and purpose of the 
libraries in programming software for the PlayStation. 


Changes Since Last Release 


This manual has been expanded in content since release 4.6 of the Run-Time Library. It combines all 


previously released material with the latest Run-Time Library 4.7 information. 


Basic Graphics Library (Chapter 7) 
Functions revised: 


VS ync() 


Controller/Peripherals Library (Chapter 12) 


Functions added: 
PadChkMtap() 
Functions revised: 
PadInfoAct() 
PadInfoM ode() 


HMD Library (Chapter 17) 
Structures revised: 


GsSEQ 


PDA Library (Chapter18) 
Functions revised: 


McxSetMem() 


Memory Card GUI Module (Chapter 19) 


Structures revised: 
sMcGuiCards 

Functions revised: 
McGuiS etExternalF ont() 


Related Documentation 


This manual should be read in conjunction with the Run-Time Library Overview, since the Overview 


summarizes the use of the libraries. 


Note: the Developer Support Web site posts current developments regarding the run-time libraries and 


also provides notice of future documentation releases and upgrades. 
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Manual Structure 
The Library Reference contains nineteen chapters providing definitions of library structures and functions. 


Generally, each chapter defines the structures and/or functions of a single library. Note, however, that 
some chapters provide definitions for several related libraries. In particular, note that Chapter 2, the 
Standard C Library, describes libc and libc2. Chapter 12, the Controller/Peripherals Library, describes 
libetc, libgun, libpad and libtap. 


Developer Reference Series 


This manual is part of the Developer Reference Series, a series of technical reference volumes covering all 
aspects of PlayStation development. The complete series is listed below: 


Manual Description 

PlayStation Hardware Describes the PlayStation hardware 
architecture and overviews its 
subsystems. 

PlayStation Operating System Describes the PlayStation operating 


system and related programming 
fundamentals. 
Run-Time Library Overview Describes the structure and purpose of 


the run-time libraries provided for 
PlayStation software development. 


Run-Time Library Reference Defines all available PlayStation run-time 
library functions, macros and structures. 
Inline Programming Reference Describes in-line programming using 


DMPSX, GTE inline macro and GTE 
register information. 

SDevTC Development Environment Describes the SDevTC (formerly "Psy-Q") 
Development Environment for PlayStation 
software development. 


3D Graphics Tools Describes how to use the PlayStation 3D 
Graphics Tools, including the animation 
and material editors. 


Sprite Editor Describes the Sprite Editor tool for 
creating sprite data and background 
picture components. 

Sound Artist Tool Provides installation and operation 
instructions for the DTL-H800 Sound Artist 
Board and explains how to use the Sound 
Artist Tool software. 


File Formats Describes all native PlayStation data 
formats. 
Data Conversion Utilities Describes all available PlayStation data 


conversion utilities, including both stand- 
alone and plug-in programs. 

CD Emulator Provides installation and operation 
instructions for the CD Emulator 
subsystem and related software. 

CD-ROM Generator Describes how to use the CD-ROM 
Generator software to write CD-R discs. 
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Manual 
Performance Analyzer User Guide 


Performance Analyzer Technical 
Reference 


DTL-H2000 Installation and Operation 


DTL-H2500/2700 Installation and 
Operation 


Typographic Conventions 


About This Manual 


Description 


Provides general instructions for using the 
Performance Analyzer software. 
Describes how to measure software 
performance and interpret the results 
using the Performance Analyser. 

Provides installation and operation 
instructions for the DTL-H2000 
Development System. 


Provides installation and operation 
instructions for the DTL-H2500/H2700 
Development Systems. 


Certain Typographic Conventions are used through out this manual to clarify the meaning of the text. The 


following conventions apply: 


Convention 
Italic 


Courier 


Medium Bold 


Blue 


Developer Support 


Sony Computer Entertainment America (SC EA) 


Meaning 


Function arguments and structure 
members. 


Literal program code. 


Types and structure/function names (in 
structure/function definitions only) 
Hyperlink to function or structure 
description 


SCEA developer support is available to licensees in North America only. You may obtain developer support 
or additional copies of this documentation by contacting the following addresses: 


Order Information 
In North America: 
Attn: Developer Tools Coordinator 


Sony Computer Entertainment America 
919 East Hillsdale Blvd., 2nd floor 


Foster City, CA 94404 
Tel: (650) 655-8000 
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Developer Support 

In North America: 

E-mail: 
DevTech_Support@playstation.sony.com 
Web: http://www.scea.sony.com/dev 


Developer Support Hotline: 

(650) 655-8181 

(Call Monday through Friday, 8 a.m. to 5 
p.m., PST/PDT) 
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viii About This Manual 


Sony Computer Entertainment Europe (SCEE) 


SCEE developer support is available to licensees in Europe only. You may obtain developer support or 
additional copies of this documentation by contacting the following addresses: 


Order Information Developer Support 

In Europe: In Europe: 

Attn: Production Coordinator E-mail: dev_support@playstation.co.uk 
Sony Computer Entertainment Europe Web: https://www-s.playstation.co.uk 
Waverley House Developer Support Hotline: 

7-12 Noel Street +44 (0) 171 447 1680 

London W1V 4HH (Call Monday through Friday, 9 a.m. to 6 
Tel: +44 (0) 171 447 1600 p.m., GMT or BST/BDT) 
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Structures 
DIRENTRY 
Directory entries. 
Library Header File Introduced Documentation Date 
libapi. lib kernel.h 2.X 12/14/98 
Structure 
struct DIRENTRY { 
char name/20]; Filename 
long attr; Attributes (dependent on file system) 
long size; File size (in bytes) 
struct DIRENTRY “next; Pointer to next file entry (for user) 
char system/8]; Reserved by system 
} 
Explanation 


Stores information relating to files registered in the file system. 


See also 
firstfile?), nextfile() 
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EvCB 
Event Control Block 
Library Header File Introduced Documentation Date 
libapi. lib kernel. 2.X 12/14/98 
Structure 
struct EvCB { 
u_long desc; Cause descriptor 
long status; Status 
long spec; Event type 
long mode; Mode 
(long *FHandler)(); Pointer to a function type handler 
long system/2]; Reserved by system 
} 
Explanation 


Stores information for each event. 


See also 
OpenEvent(), GetConf(), SetConf(). 
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EXEC 


Execution file data structure. 


Library Header File Introduced Documentation Date 
libapi. lib kernel. 2.X 12/14/98 
Structure 


struct EXEC { 

unsigned long pco0; 
unsigned long gp0; 
unsigned long t_adoar; 
unsigned long t_size; 
unsigned long d_adoar; 
unsigned long d_size; 
unsigned long b_adoar; 
unsigned long b_size; 
unsigned long s_adar; 
unsigned long s_size; 


Execution start address 

gp register initial value 

Starting address of initialized text section 
Size of text section 

Starting address of initialized data section 
Size of initialized data section 

Uninitialized data section start address 
Uninitialized data section size 

Stack start address (specified by the user) 
Stack size (Specified by the user) 


unsigned long sp; 
unsigned long fo; 
unsigned long gp; 
unsigned long ret; 
unsigned long base; 


Register shunt variable 
Register shunt variable 
Register shunt variable 
Register shunt variable 
Register shunt variable 


} 
Explanation 


Stores information for loading and executing a program. The data is stored in the first 2K bytes of the 
execution file (PS-X EXE format). By adding stack information and transfering it to Exec(), the program is 
activated. 


See also 
Exec() 
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TCB 
Task Control Block. 
Library Header File Introduced Documentation Date 
libapi. lib kernel. 2.X 12/14/98 
Structure 
struct TCB { 
long status; Status 
long mode; Mode 
unsigned long reg/NREGS]; Register saving area (specified by register designation 
macro) 
long system/6]; Reserved by system 
} 
Explanation 


Stores a context (including contents of the registers) for thread management. 


See also 
OpenTh(), ChangeTh(), GetConf(), SetConf() 
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TCBH 
Task Control Block Header. 


Library Header File Introduced Documentation Date 
libapi. lib kernel. 2.X 12/14/98 


Structure 


struct TCBH { 
struct TCB “entry; Pointer to execution TCB 
long flag; System reserved 


Explanation 
Used for thread management. entry is a pointer to the currently executing TCB. 





See also 
OpenTh(), ChangeTh() 
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ToT 


System Table Information. 


Library Header File Introduced Documentation Date 
libapi. lib kernel. 2.X 12/14/98 


Structure 
struct ToT { 
unsigned long *head; Pointer to a system table start address 
long size; System table size (in bytes) 
} 
Explanation 
Information about various system tables used by the kernel. The tables begin at address 0x00000100. 
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Functions 





calloc2 
Allocate a block in main memory. 


Library Header File Introduced Documentation Date 
libapi.lib malloc.h 3.6 12/14/98 


Syntax 

void *calloc2( 

size_tn, Number of partitions 

size_t s) Size of one partition 

Explanation 

Allocates a block of n*s bytes in the heap memory and initializes it to O. Corresponds to InitHeap2(). 





Return value 
Pointer to the allocated memory block. If allocation fails, NULL is returned. 


See also 
InitHeap2(), malloc2(), realloc2(), free2() 
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calloc3 
Allocate a block in main memory. 


Library Header File Introduced Documentation Date 
libapi. lib malloc.h 4.0 12/14/98 


Syntax 

void *calloc3 ( 

size_t n, Number of partitions 

size_t s) Size of one partition 

Explanation 

Allocates a block of n*s bytes in the heap memory and initializes it to O0. Corresponds to InitHeap3(). 


Return value 
A pointer to the allocated memory block. If allocation fails, NULL is returned. 





See also 
InitHeaps3(), malloc3(), realloc3(), frees() 
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cd 
Change default directory. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long cd( 

char *path) Pointer to the default directory path 
Explanation 


Changes the default directory path for a given file system (specified by the device name at the beginning of 
path). 





Return value 
1 if it succeeds, and O otherwise. 
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ChangeClearPAD 


Set the control driver. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


void ChangeClearPAD( 
long val) Vertical retrace line interruption clear flag 





Explanation 


if val is 1, interrupt processing in a control driver started by a vertical retrace line interrupt is completed. If 
val is O, processing is passed to a lower priority interrupt module without completion. 


See also 
StartPAD(), StopPAD(), StartCARD( (see libcard), StopoCARD( (see libcard) 
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ChangeTh 


Change the thread to be executed. 





Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long ChangeTh( 

unsigned long thread) Thread descriptor 

Explanation 

Transfers execution to the thread specified by thread. The current thread is saved in a TCB. This function 
returns when the original thread is restored. 

Before executing ChangeTh(), initialize TCB reg [R-SR] to the following: 


e = The interrupt context is 0X404 
e The main flow is 0X401 


Return value 


On success and re-execution, the function returns 1. On failure, it returns O. The return value on re- 
execution can be changed by any other thread. 


See also 
OpenTh() 
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close 
Close a file. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


int close( 
int fo) File descriptor 


Explanation 
Closes the file specified by fd. 


Return value 
fd, if the function succeeds, -1 otherwise. 


See also 
Open() 
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CloseEvent 
Close an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long CloseEvent( 
unsigned long event) Event descriptor 


Explanation 
Releases the EvCB specified by event. Must be executed in a critical section. 


Return value 
1 on success, O on failure. 


See also 
OpenEvent(), EnterCriticalSection(), SwEnterCriticalSection() 
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CloseTh 


Close a thread. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long closeTh( 
unsigned long thread) Thread descriptor 


Explanation 
Closes a thread and releases its TCB. Must be executed in a critical section. 


Return value 
1 on success, O on failure. 


See also 
OpenTh(), EnterCriticalSection(), SwEnterCriticalSection() 
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DeliverEvent 
Generate an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


void DeliverEvent( 
unsigned long ev7, Cause descriptor 
long ev2) Event class 


Explanation 


Delivers an event if the event’s current status is EVStACTIVE (event not yet generated, generation possible). 
If the event mode is EvMdINTR, the event handler function is called. If the event mode is EVMdNOINTR, the 
event status is changed to EVStALREADY (event already occurred, generation prohibited). This function 
must be executed in a critical section. 


See also 


UnDeliverEvent(), OpenEvent(), TestEvent(), EnterCriticalSection(), SwEnterCriticalSection(), DisableEvent(), 
EnableEvent(), WaitEvent(), CloseEvent() 
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DisableEvent 
Disable an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long DisableEvent( 

unsigned long event) Event descriptor 
Explanation 


Inhibits occurrence of an event specified by the descriptor event. It changes the event status to EvStWAIT 
(event generation prohibited). 


Return value 
1 on success, O on failure. 


See also 
EnableEvent() 
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DisablePAD 

Disable communication with the controller. 
Library Header File Introduced Documentation Date 
libapi. lib libapi.h 2.X 12/14/98 

Syntax 


void DisablePad(voic) 
Explanation 
Temporarily disables communication with the controller. 


Unlike StopPAD(), which deletes the controller handler activated by Vsync interrupts, this function simply 
skips controller communication by setting a flag in the handler. 


Since a controller normally communicates via Vsync interrupts, this function can be used in situations when 
the controller status is needed less frequently than every 1/60 sec. 


See also 
EnablePAD(), StopPAD() 


CONFIDENTIAL Run-Time Library Reference 


1-20 Kernel Library Functions 


EnableEvent 
Enable occurrence of an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long EnableEvent( 

unsigned long event) Event descriptor 
Explanation 


Enables occurrence of an event specified by the descriptor event. It changes the event status to 
EvStACTIVE (event not yet generated, generation possible). 


Return value 
1 on success, O on failure. 


See also 
DisableEvent(), TestEvent() 
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EnablePAD 

Enable communication with the controller. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 


void EnablePAD(voic) 


Explanation 


Enables communication with a controller which was disabled with DisablePAD(). Although a normal 
controller communicates via Vsync interrupts, this function is used only with timing longer than 1/60 sec. 
when the controller status is not needed. 


See also 
DisablePAD() 
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EnterCriticalSection 
Disable interrupts. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 
Syntax 


void EnterCriticalSection(voic) 


Explanation 
Disables interrupts (enters a critical section). 


Executes an internal system call and destroys the interrupt context. However, does not call the main 
function from the event handler callback interrupt context. 


Return value 
O when this function is called in a critical section, 1 otherwise. 


See also 
ExitCriticalSection() 
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erase 
Delete a file. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long erase( 

char *name) Pointer to a filename 
Explanation 

Deletes the file specified by name. 





This function was formerly called “delete.” 


Return value 
1 on success, O on failure. 


See also 
undelete() 
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Exception 

Cause an interrupt. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 


void Exception(voic) 


Explanation 


Causes an interrupt, and stores the current context in the execution TCB. It is also valid in a critical section. 
Executes an internal call and destroys the exception context. 





See also 
ChangeTh(), ReturnFromException() 
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Exec 

Execute an execution file. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 

long Exec( 

struct EXEC “exec, Pointer to execution file information 

long argc, Number of arguments 

char *argv) Pointer to argument 

Explanation 


Executes a module that has already been loaded into memory, using the execution file information specified 
by exec. If exec->s_addr is O, neither the stack nor frame pointers are set. 


The function does the following: 


Clears a data section without initial values to zero. 

Saves sp, fp, and gp, and then initializes them. (fp is set to the same value as sp.) 
Sets the arguments of main() in the aO and a1 registers. 

Calls the execution start address. 

Restores sp, fp, and gp after a return is made. 


It must be executed in a critical section. 


This function needs the ISO 9660 file system to run properly. Call _96_init() to initialize the system and 
_96_remove() to exit the system. 


Return value 
1 on success; O on failure. 


See also 
Load(), _96_init(), _96_remove() 
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ExitCriticalSection 

Enable interrupts. 
Library Header File Introduced Documentation Date 
libapi. lib libapi.h 2.X 12/14/98 

Syntax 


void ExitCriticalSection(voic) 


Explanation 
Enables interrupts (exits from a critical section). 


Executes an internal system call and destroys the interrupt context. However, it does not call the main 
function from the event handler callback interrupt context. 


See also 
EnterCriticalSection() 
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firstfile 

Find the first file matching a filename. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 

struct DIRENTRY “firstfile( 

char *name, Pointer to a filename 

struct DIRENTRY *dir) Pointer to the buffer holding information relating to the 


referenced file. 


Explanation 


Finds the first file corresponding to the filename pattern name, and stores data relating to this file in the 
directory dir. The wildcard characters “?” (standing for any one character) and “*” (standing for a character 
string of any length) can be used in the filename pattern. Characters specified after “*” are ignored. 





Return value 
Returns dir if it succeeds, and O otherwise. 


See also 
nextfile() 
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FlushCache 

Flush instruction cache. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 9/1/99 

Syntax 


void FlushCache(voic) 


Explanation 
Flushes the instruction cache (l-cache). Must be executed in a critical section. 


Because this function can hang if it is called during DMA transfer, it must be called after confirming that 
DMA transfer is complete. 


See also 
EnterCriticalSection() 
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format 
Initialize file system. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long format( 

char “*fs) Pointer to file system name 
Explanation 

Initializes file system fs. This function is only effective on writeable file systems. 





When initializing the Memory Card, it’s preferable to use the libcard function _card_formati(). 





Return value 
Always returns 1. 


See also 
_card_format() (see libcard) 
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free2 
Free allocated memory blocks. 


Library Header File Introduced Documentation Date 
libapi.lib malloc.h 3.6 12/14/98 

Syntax 

void free2 

(void *block) Area to be released 

Explanation 


Releases a memory block that was allocated by calloc2(), malloc2(), or realloc2(). Corresponds to 
InitHeap2(). 


See also 
InitHeap2(), calloc2(), malloc2(), realloc2() 
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free3 
Free allocated memory blocks. 


Library Header File Introduced Documentation Date 
libapi. lib malloc.h 4.0 12/14/98 


Syntax 


void free3 
(void *block) Area to be released 


Explanation 
Releases a memory block that was allocated by calloc3(), malloc3(), or realloc3\(). 


See also 
InitHeaps(), calloc3(), malloc3(), realloc3() 
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GetConf 

Get the kernel configuration. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 

void GetConf( 

unsigned long “ev, Pointer to number of event management blocks 

unsigned long *tcb, Pointer to number of task management blocks 

unsigned long *sp) Ignored 

Explanation 


Stores a system configuration parameter set by SetConf() to the address given by the pointer as the 
argument. It returns an undefined value before the execution of SetConf() because this function refers to its 
internal parameter. 


See also 
SetConf() 
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GetCr 

Get cause register value. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


unsigned long GetCr(void) 


Explanation 
Gets the value of the cause register (a coprocessor control register). 





Table 1-1: Description of Cause-Register Bits for GetCr 





Bit 


Description 





31-6 
5-2 


Reserved by the system 
Exception code 


0000 External interrupt 
0001 Not used 
0010 Not used 
0011 Not used 
0100 Address read error 
0101 Address write error 
0110 Command bus error 
0111 Data bus error 
1000 System call 
1001 Break point 
1010 Undefined command 
1011 Co-processor not mounted 
1100 Overflow 

1-0 Reserved by the system 














Return value 
The current cause register value. 


See also 
OpenTh() 
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GetGp 

Get value of gp register. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


unsigned long GetGp(voic) 


Explanation 
Gets the value of the gp register. 


Return value 
The current gp register value. 


See also 
OpenTh(), Load(), Exec() 
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GetRCnt 


Get value of a root counter. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long GetRCnt( 

long spec) Root counter 
Explanation 


Returns the current value of root counter spec. To be used when root counter spec has been set by 
SetRCnt to a polling mode (RCntMdNOINTR). 


Return value 
The 82-bit unsigned expanded counter value. On failure, it returns -1. 


See also 
SetRCnt(), StartRCnt(), StopRCnt(), ResetRCnt() 
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GetSp 

Get value of stack pointer. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


unsigned long GetSp(voic) 


Explanation 
Gets value of sp register. 


Return value 
The current sp register value. 


See also 
OpenTh(), Load(), Exec(), SetSp() 
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GetSr 

Get value of status register. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


unsigned long GetSr(voic) 


Explanation 
Gets the value of the status register. 


Table 1-2: Description of Status-Register Bits for GetSr 








Bit Description 

31-28 Co-processor installation flag (1: Installed); 
Bit 29 is GTE. 

27-11 Reserved by the system 

10 Always 1 

9-3 Reserved by the system 

2 Main flow interrupt permission (1: 
Permission) 

1 Reserved by the system 

O Interrupt permission (1: Permission) 





Return value 
The current status register value. 


See also 
OpenTh() 
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GetSysSp 

Get address of system stack. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


long GetSysSp(voic) 


Explanation 
Gets the highest address of a system stack area for event handler function execution. 


The size of the stack area is 2 K-bytes. 


Return value 
Highest address of the system stack area 


See also 
GetSp() 
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InitHeap 
Initialize heap area. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.0 12/14/98 


Syntax 

void InitHeap( 

unsigned long *head, Pointer to heap start address 
unsigned long size) Heap size (a multiple of 4, in bytes) 
Explanation 


Initializes a group of standard function library memory control functions. After using this function, malloc(), 
free(), etc. are usable. 


There is some overhead, so the entire size in bytes cannot be used. 


Must be executed in a critical section. If several executions of this function overlap, the previous memory 
control information is lost. 


See also 
malloc() (see libc/libc2) 
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InitHeap2 


Initialize heap area. 


Library Header File Introduced Documentation Date 
libapi.lib malloc.h 3.6 12/14/98 


Syntax 

void InitHeap( 

void *head, Pointer to heap start address 

long size) Heap size (a multiple of 4, in bytes) 

Explanation 

Initializes a heap area of size bytes. (Since there is overhead, the entire size in bytes cannot be used.) 





After calling this function, the library memory routines in the “malloc3” group (malloc3(), free3(), etc.) are 
usable. This routine fixes a bug in InitHeap() but has larger program size since this is a memory resident 
function. See "Memory Allocation Functions" in the Kernel chapter of the Library Overview for more 
information on the malloc systems. 


If several executions of this function overlap, the previous memory control information is lost. 


See also 
InitHeap(), malloc2(), realloc2(), calloc2(), free2() 
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InitHeap3 


Initialize heap area. 


Library Header File Introduced Documentation Date 
libapi. lib malloc.h 4.0 12/14/98 


Syntax 


void InitHeap3( 
void “head, Pointer to heap start address 
long size) Heap size (a multiple of 8, in bytes) 


Explanation 


Initializes a heap area of size bytes. If size is not divisible by 8, the remainder after dividing by 8 is 
discarded and isn’t allocated. (Since there is overhead, the entire size in bytes cannot be used.) 





After calling this function, the library memory routines in the “malloc3” group (malloc3(), free3(), etc.) are 
usable. This function is a higher speed than the “malloc2” system and is smaller in size. See "Memory 
Allocation Functions" in the Kernel chapter of the Library Overview for more information on the malloc 
systems. 





If several executions of this function overlap, the previous memory control information is lost. 


See also 
InitHeap(), InitHeap2(), malloc3(), realloc3(), calloc3(), free3() 
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InitPAD 


Initialize the controller. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long InitPAD( 
char *bufA, char *bufB, Pointers to incoming data buffers 
long /enA, long /enB) Length of incoming data buffers (in bytes) 


Explanation 


Registers a receive data buffer for the controller. For the format of this buffer, see “Receive Buffer Data 
Format” of Chapter 13 (Controller/Peripherals Library) of the Library Overview. 





Since it is possible for mistakes to occur when an unexpected controller is connected to the receive data 
length, always allocate 34 bytes. 


When using the Multi Tap, use InitTAP(). When using the gun controller, use InitGUN(. 


Return value 
Always 1. 


See also 
StartPAD(), StopPAD(), ChangeClearPAD(, InitTAP() (see libete), InitGUN( (See libetc). 
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ioctl 
Control devices. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long ioctl( 

int fd, File descriptor 

int com, Control command 

int arg) Control command argument 
Explanation 


Executes control commands on the device. Details of the commands and their arguments are given 
separately for each device. 


Return value 
1 if it succeeds and O otherwise. 


See also 
open() 
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Krom2RawAdd 

Get Kanji font pattern addresses. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 

unsigned long Krom2RawAdd( 

unsigned short sjiscode) Shift-JIS code 

Explanation 


Gets the starting address in the kernel of the font pattern for the Kanji character specified by sjiscode. 





Refer to the codeview sample in \psx\kanji\sjiscode for a list of usable fonts and the actual fonts 
themselves. 


Return value 


The starting address of a Kanji font pattern. If there is no font data corresponding to the specified Kanji 
character, a value of -1 is returned. 


Bug alert: The normal arguments are Shift-JIS code values between 0x8140~0x84BE or 
Ox889F~0x9872. If a Shift-JIS code within that region corresponds to a blank area in the code table, a font 
pattern unrelated to that code is returned as the starting address. This problem has been corrected in 
Krom2RawAdd2, so we recommend using Krom2RawAdd2 to obtain the font pattern starting address. 








See also 
Krom2RawAdd2() 
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Krom2RawAdd2 

Get shift-JIS font pattern addresses. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.2 12/14/98 

Syntax 

unsigned long Krom2RawAdd2( 

unsigned short sjiscode) Shift-JIS code 

Explanation 


Gets the starting address in the font pattern kernel for the non-Kanji/Kanji level 1 character specified by the 
sjiscode. 


(Refer to the codeview sample in \psx\kanji\sjiscode for a list of usable fonts and the actual fonts 
themselves.) 


Return value 
The font pattern starting address. When there is no font data corresponding to the specified shift-JIS code, 


an address containing a full space font pattern is returned. 


See also 
Krom2RawAdd() 
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Load 


Load an execution file. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long Load( 
char *name, Pointer to filename 
struct EXEC *exec) Pointer to execution file information 


Explanation 


Reads the PlayStation EXE format file name to the address specified by its internal header, and writes 
internal information to exec. 


This function needs the ISO 9660 file system to run properly. To initialize this system, call _96_init(); to exit 
the system, call _96_remove(). 


Calls FlushCache() internally. 


Return value 
1 if it succeeds, and O otherwise. 


See also 
Exec(), FlushCache(), _96_init(), _96_remove() 
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LoadExec 

Load and execute an execution file. 
Library Header File Introduced Documentation Date 
libapi. lib libapi.h 2.X 12/14/98 

Syntax 

void LoadExec( 

char *name, Pointer to a PS-X EXE format execution file name (fewer than 19 

characters) 

unsigned long s_adar, Stack area starting address 

unsigned long s_size) Number of bytes in stack area 

Explanation 


Calls Load() and Exec(), then reads a file name into memory and executes the file. s_addr and s_size are 
passed to Exec() and set by the structure EXEC. 








This function needs the ISO 9660 file system to run properly. To initialize this system, call _96_init(); to exit 
the system, call _96_remove(). 


See also 
Load(), Exec(), _96_init(), _96_remove() 
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LoadTest 


Load test. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long LoadTest( 
char *name, Pointer to filename 
struct EXEC *exec) Pointer to data in an execution file 


Explanation 
Writes internal information from a PS-X EXE format file name to exec. 


Return value 
The execution starting address. On failure, it returns O. 


See also 
Load() 
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Iseek 
Move a file pointer. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

unsigned long Iseek( 

int fd, File descriptor 

unsigned int offset, Number of bytes to move pointer 
int flag) Start point flag 

Explanation 


Moves a file pointer of the device indicated by the descriptor fd. 


If flag is SEEK_SET, movement starts at the start of the file; if fag is SEEK_CUR, movement starts with the 
current position. 


This function does not apply to a PC communication link. 


Return value 
The current file pointer, if it succeeds. On failure, it returns -1. 


See also 
open(), read(), write() 
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malloc2 
Allocate main memory. 


Library Header File Introduced Documentation Date 
libapi.lib malloc.h 3.6 12/14/98 


Syntax 


void *malloc2 ( 
size_t s) Size of memory block to be allocated 


Explanation 
Allocates s bytes of memory block from the heap memory. InitHeap2() must be executed in advance. 
Heap memory is defined as below: 


Low Address Module Highest Address + 4 
High Address On-board memory - 64KB 


Return value 
A pointer to the allocated memory block. On failure, NULL is returned. 


See also 
InitHeap2(), calloc2(), realloc2(), free2() 
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malloc3 
Allocate main memory. 


Library Header File Introduced Documentation Date 
libapi. lib malloc.h 4.0 12/14/98 


Syntax 

void *malloc3 ( 

size_t s) Size of memory block to be allocated 

Explanation 

Allocates s bytes of memory block from the heap memory. InitHeap3() must be executed in advance. 


Refer to the section entitled "Memory Allocation Functions" in the Kernel chapter of the Library Overview for 
the differences between the various malloc systems. 


Return value 
A pointer to the allocated memory block. If allocation fails, NULL is returned. 





See also 
InitHeaps(), calloc3(), realloc3(), free3() 
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nextfile 

Find the next file matching a filename. 
Library Header File Introduced Documentation Date 
libapi. lib libapi.h 2.X 12/14/98 

Syntax 

struct DIRENTRY *nextfile( 

struct DIRENTRY *dir) Pointer to buffer holding file information 

Explanation 


Continues a file lookup under the same conditions as the previous call to firstfile(). If it finds a corresponding 
file, it stores file information in dir. 


If the shell cover of the CD-ROM drive has been opened since the execution of the previous firstfile() call, 
this function fails, and reports that the file has not been found. 





Return value 
dir if it succeeds, and O otherwise. 


See also 
firstfile() 
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open 
Open a file. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long open( 
char *devname, Pointer to a filename 
int flag) Open mode 


Explanation 


Opens a device for low-level input/output, and returns the descriptor. The values of flag are dependent on 
the device; they can be the following: 





Table 1-3: Open Modes 








Macro Open mode 
O_RDONLY Read only 
O_WRONLY Write only 

O_RDWR Both read and write 
O_CREAT Create new file 
O_NOBUF Non-buffer mode 
O_NOWAIT Asynchronous mode 





Return value 
The file descriptor, if the function succeeds. On failure, it returns -1. 


See also 
close() 
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OpenEvent 
Open an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long OpenEvent( 

unsigned long desc, Cause descriptor 

long spec, Event type 

long mode, Mode 

long *func() Pointer to the handler function 
Explanation 


Secures an EvCB for an event with the descriptor desc and event class spec. Must be executed in a critical 
section. 


Return value 
The event descriptor, if the function succeeds. On failure, it returns -1. 


See also 
CloseEvent(), DeliverEvent(), EnterCriticalSection() 
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OpenTh 

Open a thread. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.x 12/14/98 

Syntax 

unsigned long OpenTh( 

unsigned long (*func)(), Pointer to the execution start function 

unsigned long sp, Stack pointer value 

unsigned long gp) Global pointer value 

Explanation 


Secures a TCB for a given thread, and initializes it with the arguments given. Must be executed in a critical 
section. 


The thread can be executed using ChangeThi(). 


Return value 
The thread descriptor, if the function succeeds. On failure, it returns -1. 


See also 
CloseTh(), ChangeTh() 
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read 
Read data from a file 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long read ( 

long fd, File descriptor 

void *buf, Pointer to read buffer address 
long n) Number of bytes to read 
Explanation 

Reads n bytes from the descriptor fd to the area specified by buf. 


Return value 
The actual number of bytes read into the area. An error returns -1. 


See also 
open(), Iseek() 
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realloc2 
Change a block’s memory allocation. 


Library Header File Introduced Documentation Date 
libapi.lib malloc.h 3.6 12/14/98 


Syntax 


void *realloc2( 
void “block, Area to be reallocated 
size_t s) Size of area to be reallocated 





Explanation 


Changes the size of the memory block previously allocated to s bytes. Same as malloc2() when block is 
NULL. Corresponds to InitHeap2(). 


Return value 


A pointer to the reallocated memory block. The address may be from the original. If reallocation fails, NULL 
is returned, and the original block is not released. 





See also 
calloc2(), malloc2(), free2() 
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realloc3 
Change a block’s memory allocation. 


Library Header File Introduced Documentation Date 
libapi. lib malloc.h 4.0 12/14/98 


Syntax 


void *realloc3 
(void “block, Area to be reallocated 
size_t s) Size of area to be reallocated 





Explanation 


Changes the size of the memory block previously allocated to s bytes. When block is NULL, it operates in 
the same way as malloc3(). 


Return value 


A pointer to the reallocated block address; this address may be different from the original. If reallocation 
fails, NULL is returned, and the original block is not released. NULL is also returned if s is O. 





See also 
InitHeapsi(), calloc3(), malloc3\(), free3() 
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rename 
Change a file name. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long rename( 
char “src, Pointer to the old filename 
char *dest) Pointer to the new filename 


Explanation 


Changes a filename from src to dest. In both cases, the full path from the device name must be specified. 
This function is only effective on writeable file systems. 





Return value 
1 if it succeeds, and O otherwise. 


See also 
open() 
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ResetRCnt 


Reset a root counter. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long ResetRCnt( 
long spec) Root counter specification 


Explanation 
Resets the root counter spec to 0. 


Return value 
1 if it succeeds, and O otherwise. (O is always returned if you specify RCntCNTS, since it can’t be set.) 


See also 
SetRCnt(), GetRCnt(), StartRCnt(), StopRCnt() 
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ReturnFromException 

Return from exception. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 


void ReturnFromException(voia) 


Explanation 
Accesses the exception context and returns from exception processing. It is used in an event handler or 
callback function. 


See also 
Exception( 
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SetConf 


Modify the kernel configuration. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long SetConf( 

unsigned long ev, Number of event control block (EvCB) elements 
unsigned long tcb, Number of task control block (TCB) elements 
unsigned long sp) Ignored 


Explanation 


Modifies system configuration parameters. The contents of event and task control blocks, and all settings 
for event handlers and callback functions in each library, are destroyed. However, file descriptors are not 
affected (all the descriptors should be closed before SetConf() call) because most of the device drivers are 
driven by the event handler. 








All patches to the kernel are invalidated. 





This function should be executed at the head of the first execution file. The operations of libraries initialized 
before the execution of this function are not ensured. 


This function eliminates the ISO-9660 file system installed in the kernel immediately after activation (call 
_96_init() to reinstate). The result of operations on the opened files are not predictable. 








If the number of the designated elements exceeds the maximum, the operation of the system after the 
execution of this function is not defined. 


Return value 
1 if the function succeeds, O otherwise. 


See also 
GetConf() 
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SetMem 


Modify the valid memory size. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


void SetMem( 
unsigned long n) Valid memory size (in megabytes) 


Explanation 

Changes the valid memory size to n. It must be 2 or 8 (megabytes); any other values are ignored. 
Memory access out of the valid range causes a CPU exception regardless of how much physical memory 
is present. 


See also 
SetConf() 
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SetRCnt 


Set a root counter. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long SetRCnit( 

long spec, Root counter specification 
unsigned short target, Target value 

long mode) Mode 

Explanation 


Sets the root counter in spec to the target value in target, and the mode in mode. 


Return value 
1 if it succeeds, and O otherwise. (0 is always returned if you specify RCntCNTS, since it can’t be set.) 


See also 
GetRCnt(), StartRCnt(), StooRCnt(), ResetRCnt() 


Run-Time Library Reference CONFIDENTIAL 


Kernel Library Functions 1-65 


SetSp 


Set the stack pointer. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


unsigned long SetSp/( 
unsigned long new-sp) value to set sp register 


Explanation 
Sets the sp register to the value new-sp. 


Return value 
The previous sp register value. 


See also 
OpenTh(), Load(), Exec(), GetSp() 
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StartPAD 

Start reading the controller. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 


long StartPAD(voic) 


Explanation 


Triggered by the interruption of a vertical retrace line, this function starts to read the controller. 
ChangeClearPAD (1) is executed internally. 


Interrupts are permitted. 


Return value 
Always returns 1. 


See also 
InitPAD(), ChangeClearPAD(), StopPAD() 
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StartRCnt 


Start a root counter. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long StartRCnt( 
long spec) Root counter 


Explanation 
Enables interrupts for root counter spec. 


Return value 
1 if it succeeds, and O otherwise. (O is always returned if you specify RCntCNTS, since it can’t be set.) 


See also 
GetRCnt(), ResetRCnt(), SetRCnt(), StopRCnt() 
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StopPAD 


Stop reading the controller. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 
void StopPAD(voia) 


Explanation 
Stops reading the controller. Interrupts are not permitted. 


See also 
InitPAD(), ChangeClearPAD(), StartPAD() 
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StopRCnt 


Stop a root counter. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long StopRCnt( 
long spec) Root counter 


Explanation 
Disables interrupts for root counter spec. 


Return value 
1 if it succeeds, and O otherwise. (O is always returned if you specify RCntCNTS, since it can’t be set.) 


See also 
StartRCnt(), SetRCnt(), ResetRCnt(), GetRCnt() 
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SweEnterCriticalSection 
Suppress interrupts. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 
Syntax 


void SwEnterCriticalSection(voia) 


Explanation 


Suppresses interrupts. Because no system call interrupt is generated internally, this function can be 
invoked in event handling and callback functions. It must be executed in a critical section. 


See also 
EnterCriticalSection(), SwExitCriticalSection() 
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SweExitCriticalSection 
Enable interrupts. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 
Syntax 


void SwExitCriticalSection(voic) 


Explanation 


Enables interrupts. Because no system call interrupt is generated internally, this function can be invoked in 
event handling and callback functions. 


Must be executed in a critical section. 


See also 
EnterCriticalSection(), SwExitCriticalSection() 
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SystemError 
Display the system error screen. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


void SystemError( 
char c, Error identification character (Alphabetic character) 
long n) Error identification code (0 to 999) 


Explanation 
Displays a detected system error for the user. On the PlayStation®, it calls exit(). 
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TestEvent 
Test an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long TestEvent( 

unsigned long event) Event descriptor 
Explanation 


Checks to see whether or not the event specified by the descriptor event has occurred. If so, the function 
restores the event state to EvStACTIVE. 


Return value 
1 if the event is found to have occurred, O otherwise. 


See also 
DeliverEvent(), EnableEvent(), WaitEvent(), OpenEvent(), CloseEvent(), UnDeliverEvent(), DisableEvent() 


CONFIDENTIAL Run-Time Library Reference 


1-74 Kernel Library Functions 


undelete 
Resurrect a file. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 


long undelete( 
char *name) Pointer to filename 


Explanation 
Resurrects the previously deleted file specified by name. 


Return value 
1 if it succeeds, and O otherwise. 


See also 
erase() 
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UnDeliverEvent 

Cancel an event. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 

void UnDeliverEvent( 

unsigned long ev7, Cause descriptor 

long ev2) Event class 

Explanation 


Returns event state from EvStALREADY (already occurred) to EvStACTIVE if the event mode is 
EvMdNOINTR. Must be executed in a critical section. 


See also 
DeliverEvent(), EnableEvent(), OpenEvent(), TestEvent(), WaitEvent(), EnterCriticalSection() 
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WaitEvent 


Wait for the occurrence of an event. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

long WaitEvent( 

unsigned long event) Event descriptor 
Explanation 


Waits until an event specified by the descriptor event occurs, and returns after restoring the event state to 
EvStACTIVE. 


Return value 
1 if it succeeds, and O otherwise. 


See also 
TestEvent(), OpenEvent(), CloseEvent(), DeliverEvent(), UnDeliverEvent(), DisableEvent(), EnableEvent() 
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write 
Write data to a file. 
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Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 

int write( 

int fd, File descriptor 

char *buf, Pointer to the write buffer address 
int n) Number of bytes to be written 
Explanation 


Writes n bytes from the descriptor fd to the area specified by buf. 


Return value 


The number of bytes actually written to the area. If there is an error, -1 is returned. 


See also 
open(), Iseek() 
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_96 init 

Install the ISO-9660 file system. 
Library Header File Introduced Documentation Date 
libapi. lib libapi.h 2.X 12/14/98 

Syntax 


void _96_init(voia) 


Explanation 
Installs the ISO-9660 file system driver that manages access to the CD-ROM. 


See also 
_96_remove() 
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_96 remove 

Remove the ISO-9660 file system. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 

Syntax 


void _96_remove(voic) 


Explanation 
Removes the ISO-9660 file system driver that manages access to the CD-ROM. 


See also 
_96_init() 
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_boot 
Reboot the system. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 2.X 12/14/98 


Syntax 
void _boot(voia) 


Explanation 
Reboots the system. This function is useful for demonstration programs; don’t use it for general title 
applications. 
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_get_errno 

Get the latest I/O error code. 
Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 

Syntax 


int _get_errno(voia) 


Explanation 
Gets the latest error code from all file descriptors. (Error codes are defined in sys/errno.h.) 


Return value 
Error code. 


See also 
_get_error() 
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_get_error 
Get an error code for a file descriptor. 


Library Header File Introduced Documentation Date 
libapi.lib libapi.h 3.0 12/14/98 


Syntax 


int_get_error( 
int fo) File descriptor 


Explanation 
Gets the most recent error code of the specified file descriptor. (Error codes are defined in sys/errno.h.) 


Return value 
Error code. 


See also 
get_errno() 
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abs 
Calculate absolute value. 


Library Header File Introduced Documentation Date 
libcNibc2. lib abs.h 2.X 12/14/98 

Syntax 

int abs( 

int /) Integer 

Explanation 


Calculates the absolute value of the integer i. On the R3000, int and long are the same size, so this function 
is equivalent to labs(). 


Return value 
Absolute value of the argument. 





See also 
labs() 
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atoi 

Convert a string to an integer. 
Library Header File Introduced Documentation Date 
libcNibc2. lib convert.h 2.X 12/14/98 

Syntax 

int atoi( 

char *s) Pointer to a character string 

Explanation 


Converts a string to its integer equivalent. On this system, it is equivalent to atol(). 


Return value 
Integer equivalent of s. 


See also 
atol(), strtol(), strtoul() 
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atol 

Convert a character string to a long. 
Library Header File Introduced Documentation Date 
libcNibc2. lib convert.h 2.X 12/14/98 

Syntax 

long atol( 

char *s) Pointer to a character string 

Explanation 


Converts a string to its long equivalent. On this system, it is equivalent to atoi(). 


Return Value 
Integer equivalent of s. 


See also 
atoi(), strtol(), strtoul 
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bcmp 

Compare memory blocks. 
Library Header File Introduced Documentation Date 
libcNibc2.lib memory.h 2.X 12/14/98 

Syntax 

int bcmp( 

u_char *b1, Pointer to first block 

u_char *b2, Pointer to second block 

int n) Number of bytes to be compared 

Explanation 


Compares the first n bytes of b1 and b2. 


Return value 
0 if b1== b2. 
<0 if b1 < b2 
>0 if b1 > b2. 


See also 
memcmp() 
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bcopy 

Copy a memory block. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void bcopy( 

u_char “src, Pointer to copy source 

u_char “dest, Pointer to copy destination 

int n) Number of bytes copied 

Explanation 


Copies the first n bytes of src to dest. 


See also 
memcpy(), memmove() 
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bsearch 

Perform a binary search. 
Library Header File Introduced Documentation Date 
libCNibc2. lib stdlib.h 2.X 12/14/98 

Syntax 

void *bsearch( 

u_char *key, Pointer to the value to be searched for 

u_char *base, Pointer to the array to be searched 

size_tn, Number of elements 

size_t w, Size of one element 

int (“fcmp)() Pointer to address of comparison function 

Explanation 

Carries out a binary search on a table of n items (of item size w) starting from base, for an item matching 

key. 


Return value 
The address of the first item matching the search key. If no matching item is found, O is returned. 
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bzero 

Fill a memory block with zeros. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void bzero( 

u_char *p, Pointer to memory block 

int n) Size 

Explanation 


Sets n bytes to the value O, starting from p.. 
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calloc 
Allocate main memory. 


Library Header File Introduced Documentation Date 
liocNibc2.lib malloc.h 2.X 12/14/98 

Syntax 

void *calloc( 

size_tn, Number of blocks 

size_t s) Size of block 

Explanation 

Allocates a memory area of N blocks of s bytes each from the heap and initializes it to O. 


Return value 
A pointer to the memory area allocated. If the function fails, it returns NULL. 





See also 
malloc(), realloc(), free() 
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exit 

Terminate a program normally. 
Library Header File Introduced Documentation Date 
libcNibc2. lib Stdlib.h 2.X 12/14/98 

Syntax 

void exit( 

int err) Error code 

Explanation 


When executed on the PlayStation®, a system error notice window is displayed (including the error code), 
and the system enters an infinite loop. When executed on a development machine, the program currently 
being executed is terminated, and the system returns to the debug monitor. 
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free 

Release an allocated memory block. 
Library Header File Introduced Documentation Date 
libcNibc2. lib malloc.h 2.X 12/14/98 

Syntax 

void free( 

void *block) Pointer to a memory block allocated by a function such as malloc(). 

Explanation 


Releases a memory block that was allocated by calloc(), malloc() or realloc(). 


See also 
calloc(), malloc(), realloc() 
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getc 

Get one character from a stream. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 12/14/98 

Syntax 

char getc( 

int fa) File descriptor 

Explanation 


Gets one character from the file indicated by fd. 
Devices and systems with a block size of 1 may all be used as the standard input/output stream as follows: 


0); 
1); 
<device name>, O_RDONLY); 
<device name>, O_WRONLY); 


e Close 
e Close 
e Open 
e Open 


eee, 





ae a 


Return value 
The character read. If the end of file is reached, or when an error is generated, the function returns EOF. 


See also 
getchar(), gets(), putc() 
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getchar 

Get one character from the standard input stream. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 12/14/98 

Syntax 


char getchar(voic) 


Explanation 
Gets one character from the standard input stream. It is the same as getc(stdin). 


Return value 
The character read. If the end of file is reached, or when an error is generated, the function returns EOF. 


See also 
getc(), gets(), putchar() 
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gets 

Read a character string from standard input. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 12/14/98 

Syntax 

char *gets( 

char *s) Pointer to storage destination for input character string 

Explanation 


Reads a character string from the standard input stream (stdin) and stores it in s until a new-line character 
is read. 


Return value 


If this function succeeds, it returns s. The new-line character is discarded and a null character is written 
immediately after the last character read. If it reaches the end of the file, or if an error is generated, it returns 
NULL. 


See also 
getc(), getchar(), puts() 
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ISXXXX... 


Test characters. 


Library Header File Introduced Documentation Date 
libcNibc2. lib ctype.h 2.X 12/14/98 


Syntax 
isXXXX(c) Character 


Explanation 
These are macros that perform the following tests on the character c: 


Table 2-1: Character Macros 








Name Conditions 

isalnum(c) isalpha(c) II isdigit(c) 

isaloha(c) isupper(c) II islower(c) 

isascii(c) ASCII character 

iscntrl(c) Control character 

isdigit(c) Decimal 

isgraph(c) Printing characters other than space 

islower(c) Lower-case character 

isprint(c) Printing characters including space 

ispunct(c) Printing characters other than space and 
alohanumerics 

isspace(c) Space, new page, new line, restore, tab 

isupper(c) Upper-case character 

isxdigit(c) Hexadecimal 





Return value 
Non-zero if the character c satisfies the test conditions; O otherwise. 


See also 
toascii(), tolower(), toupper() 
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labs 


Calculate absolute value. 
Library Header File Introduced Documentation Date 
libCNibc2. lib convert.h 2.X 12/14/98 


Syntax 

long labs( 

long /) Long value 
Explanation 

Calculates the absolute value of i. 


Return value 
Absolute value of the argument. 





See also 
abs() 
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longjmp 

Non-local jump. 
Library Header File Introduced Documentation Date 
libcNibc2. lib setimp.h 2.X 12/14/98 


Syntax 


void longjmp( 
jmp_buf p, Environment storage variable. 
int val) setjmp() Return value 


Explanation 
Makes a non-local jump to the destination specified by p. 


See also 
setimp() 
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malloc 


Allocate main memory. 
Library Header File Introduced Documentation Date 
libcNibc2. lib malloc.h 2.X 12/14/98 


Syntax 

void *malloc( 

size_t s) Number of bytes to be allocated 
Explanation 

Allocates a block of s bytes from the memory heap. 





Note that the memory heap is defined as follows when the user program is activated: 


Bottom address: top address of module + 4. 
Top address: available memory -32KB. 


This function has a bug whereby the area is not completely released in free(). This function can be replaced 
by malloc2() or malloc3() from libapi. For more information, refer to the Kernel Library chapter of the Run- 
Time Library Overview. 


Return value 
A pointer to the secured memory block. If allocation fails, NULL is returned. 


See also 
calloc(), realloc(), free() 
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memchr 

Search a memory block for a character. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void *memchr( 

u_char *s, Pointer to memory block 

u_char c, Character 

int n) Number of bytes 

Explanation 


Searches the memory block of n bytes starting from s, looking for the first appearance of the character c. 


Return value 
A pointer to the location at which c was found. If c was not found, NULL is returned. 


See also 
strchr() 
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memcmp 

Compare memory blocks. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void *memcmp( 

u_char *s7, Pointer to first memory block 

u_char *s2, Pointer to second memory block 

int n) Number of bytes to be compared 

Explanation 


Compares the first n bytes of s1 and s2. 


Return value 


Oif s1 =s2. 
<0 if s1< $2. 
>0 ifs? > S2. 


See also 
bcmp() 
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memcpy 

Copy a memory block. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void *memcpy( 

u_char “dest, Pointer to copy destination memory block 

u_char “src, Pointer to copy source memory block 

int n) Number of bytes copied 

Explanation 


Copies the first n bytes of src to dest. 


Return value 
Pointer to destination (dest). 


See also 
bcopy() 
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memmove 

Copy a memory block. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void *memmove( 

u_char “dest, Pointer to copy destination memory block 

u_char “src, Pointer to copy source memory block 

int n) Number of bytes copied 

Explanation 


Copies the first n bytes of src to dest. The block is copied correctly, even between overlapping objects. 





Return value 
Pointer to destination (dest). 


See also 
bcopy(), memcpy() 
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memset 

Write a character to a memory block. 
Library Header File Introduced Documentation Date 
libcNibc2. lib memory.h 2.X 12/14/98 

Syntax 

void *memset( 

u_char *s, Pointer to memory block 

u_char c, Character 

int n) Number of characters 

Explanation 


Writes c to the first n bytes of s. 


Return value 
Pointer to block (s). 
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printf 
Print formatted output. 


Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 2/24/99 


Syntax 

int printf( 

char “fmt/, argument...) | Pointer to input format character string 

Explanation 

See a C language reference. Conversion directives f, e, E, g and G cannot be used. Use printf2() from 
libmath for floating-point representations. 


Note: When printf() (or printf2(), putchar(), or puts()) is being executed in the main flow, and an interrupt 
occurs, text corruption or a hang-up can result if printf) is called during the interrupt. Therefore, pay 
attention to the call timing when calling printf) in an interrupt. 





Return value 
The length of the output character string. If an error is generated, the function returns NULL. 


See also 
sprintf) 
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putc 

Output one character to a stream. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 12/14/98 

Syntax 

void putc( 

char c, Output character 

int fa) File descriptor 

Explanation 


Outputs a character c to the file indicated by fd. 


Return value 
c if the function succeeds; EOF if an error is generated. 


See also 
getc(), putchar(), puts() 
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putchar 

Output one character to the standard output stream. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 2/24/99 

Syntax 

void putchar( 

char c) Output character 

Explanation 


Outputs a character c to standard output. It is the same as putc(stdout). 





Note: When printf() (or printf2(), putchar(), or puts()) is being executed in the main flow, and an interrupt 
occurs, text corruption or a hang-up can result if printf) is called during the interrupt. Therefore, pay 
attention to the call timing when calling printf) in an interrupt. 


Return value 
c if the function succeeds; EOF if an error is generated. 


See also 
getchar(), putc(), puts() 
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puts 

Output a character string to the standard output stream. 
Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 2/24/99 

Syntax 

void puts( 

char *s) Pointer to output character string 

Explanation 


Outputs a character string ending in NULL to the standard output stream (stdout), and finally outputs a 
newline character. 


Note: When printf() (or printf2(), putchar(), or puts()) is being executed in the main flow, and an interrupt 
occurs, text corruption or a hang-up can result if printf) is called during the interrupt. Therefore, pay 
attention to the call timing when calling printf in an interrupt. 





Return value 
A non-negative value, if the function succeeds; EOF if an error is generated. 


See also 
gets(), putc(), putchar() 
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qsort 

Perform a quick sort. 
Library Header File Introduced Documentation Date 
liocNibc2.lib gsort.h 2.X 12/14/98 

Syntax 

void qsort( 

void *base, Pointer to storage destination of array to be sorted 

size_tn, Number of elements 

size_t w, Size of on element 

int (“fcmp)() Pointer to address of comparison function 

Explanation 


Quick-sorts a table of n items (of item size w) starting with base, with femp as the comparison function. 
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rand 

Generate a random number. 
Library Header File Introduced Documentation Date 
libcNibc2. lib rand.h 2.X 12/14/98 

Syntax 


int rand(voia) 


Explanation 
Generates a pseudo-random number from O to RAND_MAX (Ox7FFF=32767). 


Return value 
The generated pseudo-random number. 


See also 
srand() 
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realloc 

Change heap memory allocations. 
Library Header File Introduced Documentation Date 
libcNibc2. lib malloc.h 2.X 12/14/98 

Syntax 

void *realloc( 

void *block, Pointer to a block allocated by a function such as malloc() 

size_t s; New size 

Explanation 


Takes a previously allocated block and contracts it or expands it to s bytes. If block is NULL, this function 
works in the same way as malloc. 


Return value 
The address of the reallocated block. May be different from the old address. 


If the allocation fails, the function returns NULL, and the old block is not released. 


See also 
calloc(), malloc(), free() 
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setjmp 

Defines non-local jump destination. 
Library Header File Introduced Documentation Date 
libcNibc2. lib setimp.h 2.X 12/14/98 

Syntax 

int setjmp( 

jmp_buf p) Environment storage variable 

Explanation 


Stores the destination information for a non-local jump at p. If longjmp(p, val) is executed, the system 
returns from setimp(). 


Return value 
Returns the value given to the second argument of longjmp() when the jump is executed. 








See also 
longjmp() 
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sprintf 
Write formatted output to a string. 


Library Header File Introduced Documentation Date 
libcNibc2. lib stdio.h 2.X 12/14/98 

Syntax 

long sprintf( 

char *s, Storage location for variable character string 

const char *fmt/,argument...)) Input format character string 

Explanation 

This function is like printf), except that it writes the formatted output to a string, followed by a null 

character. Refer to a C language reference for a detailed explanation of the input format. 


The conversion designators [f] [e] [E] [g] [G] are not supported. Use sprintf2() from the math library to 
display floating points. 


Return value 
The length of the output character string. NULL is returned when an error occurs. 


See also 
printf), sprintf2() see libmath) 


CONFIDENTIAL Run-Time Library Reference 


2-34 Standard C Library Functions 


srand 

Initialize the random number generator. 
Library Header File Introduced Documentation Date 
libcNibc2. lib rand.h 2.X 12/14/98 

Syntax 

void srand( 

u_long seed) Random number seed 

Explanation 


Sets a new starting point for random number generation. The default is 1. 


See also 
rand() 


Run-Time Library Reference CONFIDENTIAL 


Standard C Library Functions 2-35 


strcat 

Concatenate character strings. 
Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 

Syntax 

char *strcat( 

char “dest, Pointer to destination string 

char “src) Pointer to source string 

Explanation 


Appends the character string src to the end of the character string dest. 


Return value 
Address of destination string (dest). 


See also 
strncat() 
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strchr 

Search for the first location at which a character appears in a string. 
Library Header File Introduced Documentation Date 
libcNibc2. lib strings.h 2.X 12/14/98 

Syntax 

char *strchr( 

char *s, Pointer to character string searched 

char c) Character searched for 

Explanation 


Searches for the first location at which the character c appears in the character string s. 


Return value 
Address of the location at which c appears. If c has not been found, NULL is returned. 


See also 
strrchr(), strpbrk() 
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strcmp 
Compare character strings. 


Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 


Syntax 


int stremp( 
char *s7, Pointer to character string 1 
char *s2) Pointer to character string 2 


Explanation 
Compares the character string s2 with the character string s1, treating each character as an unsigned char. 


Return value 
<0 if si<s2 


Oifs7 = s2 
>0 if s1 > s2 


See also 
strncmp() 
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strcpy 
Copy a character string. 


Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 


Syntax 


char *strcpy( 
char “dest, Pointer to destination location. 
char “src) Pointer to source character string 


Explanation 
Copies the character string src to the character string dest. 


Return value 
Pointer to destination string (dest). 


See also 
strncpy() 
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strcspn 

Search for a string of characters not included in the a character set. 
Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 

Syntax 

int strcspn( 

char *s7, Pointer to string 

char *s2) Pointer to character set 

Explanation 


Returns the length of the first part of the character string s7 consisting only of characters not included in 
the character string s2. 


Return value 
The length of the partial character string found. 


See also 
strpbrk(), strtok(), strspn() 
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strlen 
Count characters in a string. 


Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 


Syntax 
int strlen( 
char *s) Pointer to character string 


Explanation 
Counts the number of characters in string s. 


Return value 
The number of characters in the string. 


Run-Time Library Reference CONFIDENTIAL 


Standard C Library Functions 2-41 


strncat 

Concatenate character strings. 
Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 

Syntax 

char *strncat( 

char “dest, Pointer to destination string 

char “src, Pointer to source string 

int n) Number of characters concatenated 

Explanation 


Appends the first n characters from src to the end of the character string dest. 


Return value 
Pointer to destination string (dest). 


See also 
strcat() 
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strncmp 

Compare character strings. 
Library Header File Introduced Documentation Date 
libcNibc2. lib strings.h 2.X 12/14/98 

Syntax 

int strncmp( 

char *s7, Pointer to character string 1 

char *s2, Pointer to character string 2 

int n) Number of characters compared 

Explanation 


Compares the first n characters of s1 and s2, treating each character as an unsigned char. 

Return value 

One of the following values, depending on the comparison result (the values are the same as for strcmp). 
<0 if s7<s2 

Oifs?7=s2 

>O ifs? >s2 





See also 
strcmp() 
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strncpy 

Copy a character string. 
Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 

Syntax 

char *strncpy( 

char “dest, Pointer to destination string 

char “src, Pointer to source string 

int n) Number of bytes to copy 

Explanation 


Copies the first n bytes of src to the character string dest. 


Return value 
Pointer to destination string (dest). 


See also 
strcpy) 
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strpbrk 

Search for the first occurrence of a character in a character set. 
Library Header File Introduced Documentation Date 
libcNibc2. lib strings.h 2.X 12/14/98 

Syntax 

char *strpbrk( 

char *s7, Pointer to character string searched 

char *s2) Pointer to character group 

Explanation 


Searches for the first location at which any of the characters contained in the character string s2 appear 
within the character string s1. 


Return value 
The address of the first character found. If no character was found, NULL is returned. 


See also 
strcspn(), strtok() 
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strrchr 


Search for the last location of a character in a character string. 


Library Header File Introduced 
libcNibc2.lib strings.h 2.x 
Syntax 
char *strrchr( 
char *s, Pointer to character string searched 
char c) Character searched for 
Explanation 


Searches for the last occurrence of the character c within the character string s. 


Return value 
The address of the last occurrence of c. If c does not occur, NULL is returned. 


See also 
strchr(), strobrk() 
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strspn 

Search for the part of a string consisting solely of characters in a character set. 
Library Header File Introduced Documentation Date 
libcNibc2.lib strings.h 2.X 12/14/98 

Syntax 

int strspn( 

char *s7, Pointer to string 

char *s2) Pointer to character set 

Explanation 


Returns the length of the first part of the character string s1 which consists solely of characters included in 
the character string s2. 


Return value 
The length of the partial character string found. 


See also 
strcspn(), strobrk() 
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strstr 
Search for the location of a partial character string. 
Library Header File Introduced 
libcNibc2.lib strings.h 2.x 
Syntax 
char *strstr( 
char *s1, Pointer to character string searched 
char *s2) Pointer to string searched for 
Explanation 


Searches for the first location of character string s2 within character string s1. 


Return value 
The address of s2. If it was not found, the function returns NULL. 


See also 
strchr() 
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strtok 

Search for a string demarcated by characters in a character set. 
Library Header File Introduced Documentation Date 
libcNibc2. lib strings.h 2.x 12/14/98 

Syntax 

char *strtok( 

char *s1, Pointer to character string searched 

char *s2) Pointer to separator characters 

Explanation 





Treats character string s1 as a set of tokens punctuated by one or more characters from the separator 
character string s2. The first call in the sequence searches s1 for the first character that is not contained 
within S2. 


The first time strtok() is called, the starting address of the first token of s1 is returned, and a NULL character 
is written in immediately after this token. The address of s7 is stored in the function, and then, when strtok() 
is called with NULL entered as the first argument, a search is carried out until there are no tokens left in the 
character string s7. 





Return value 
The starting address of the tokens found in s7. If it does not find any s1 tokens, strtok() returns NULL. 


See also 
strcspn(), strobrk() 
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strtol 

Convert a character string to a long. 
Library Header File Introduced Documentation Date 
libcNibc2. lib convert.h 2.X 12/14/98 

Syntax 

long strtol( 

char *s, Pointer to character string 

char **endp, Storage destination of pointer to a non-convertible character string 

unsigned int base) Radix specification 

Explanation 

Converts a character string s to a long (the same as an int in R3000). s must be formatted as follows: 

[ws][sn][ddd] 

[ws] white space (may be omitted) 

[sn] sign (may be omitted) 

[ddd] number string (may be omitted) 


The value of base determines the format of [ddd]. The letters a (or A) thru z (or Z) are ascribed values from 
10-35. Only values less than base may be included in [ddd]. For some values of base, optional characters 
may precede the sequence of letters and digits following the sign (if present). 














Table 2-2 
Base Value Optional Characters 
2 Ob, OB 
8 “O,” “o” 
16 Ox, OX 





The function strtol() stops converting when it encounters a non-convertible character, and if endp is not 
NULL, it sets endp as the pointer to the character at which it stopped converting. 


Return value 
The result obtained by converting the input value s to a long. If an error is generated, it returns O. 


See also 
atol(), strtoul() 
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strtoul 

Convert a character string to an unsigned long. 
Library Header File Introduced Documentation Date 
libcNibc2. lib convert.h 2.X 12/14/98 

Syntax 

u_long strtoul( 

char *s, Pointer to character string 

char **endp, Storage destination of pointer to a non-convertible character string 

int base) Radix specification 

Explanation 


Converts a character string s to unsigned long type (the same as unsigned int type in R3000). s must be 
formatted as follows. 


[ws][sn][ddd] 

[ws] white space (may be omitted) 
[sn] sign (may be omitted) 

[ddd] number string (may be omitted) 


The value of base determines the format of [ddd]. The letters a (or A) thru z (or Z) are ascribed values from 
10-35. Only values less than base may be included in [ddd]. For some values of base, optional characters 
may precede the sequence of letters and digits following the sign (if present). 














Table 2-3 
Base Value Optional Characters 
2 Ob, OB 
8 “O,” “o” 
16 Ox, OX 





The function strtoul() stops converting when it encounters a non-convertible character, and if endp is not 
NULL, it sets endp as the pointer to the character at which it stopped converting. 


Return value 
The result obtained by converting the input value s to a long. 


See also 
atol(), strtol() 
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toascii 

Mask bit 7 of the input value. 
Library Header File Introduced Documentation Date 
libcNibc2. lib ctype.h 2.X 12/14/98 

Syntax 

toascii (c) Value 

Explanation 


This macro returns an ASCII value equal to the low 7 bits of the input. 


Return value 
The low 7 bits of the input value c. 


See also 
iSXXXX() 
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tolower 

Convert a letter to lower-case. 
Library Header File Introduced Documentation Date 
libcNibc2. lib ctype.h 2.X 12/14/98 

Syntax 

tolower(c) Character 

Explanation 


This macro converts a character c to lower case. The behavior of this macro when it is given a value not an 
upper-case letter is undefined. 


Return value 
The lower-case letter that corresponds to c. 


See also 
toupper(), iSXxxXX() 
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toupper 

Converts a character to upper case. 
Library Header File Introduced Documentation Date 
libcNibc2. lib ctype.h 2.X 02/15/98 

Syntax 

toupper(c) Character 

Explanation 


This macro converts a character c to upper case. The behavior of this macro when it is given a value not a 
lower-case letter is undefined. 


Return value 
The upper-case letter that corresponds to the character c. 


See also 
tolower(), isXXXX() 
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Math Library Functions 3-3 


acos 


Arccosine. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double acos( 
double x) Value whose arccosine is to be determined, ranging from -1 to 1 


Explanation 

Determines the arccosine of x. 

Return value 

Arccosine of x, ranging from O to pi. 

Error handling: if fabs(x)>1, O is returned, and math_errno is set to EDOM (domain error). 


See also 
cos(), asin(), atan(), atan2() 
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3-4 Math Library Functions 


asin 
Arcsine. 


Library Header File Introduced Documentation Date 
libmath.lib libmath.h 3.0 12/14/98 


Syntax 


double asin( 
double x) Value whose arcsine is to be determined, ranging from -1 to 1. 


Explanation 
Determines the arcsine of x. 


Return value 
Arcsine of x, ranging from -pi/2 to pi/2. 


Error handling: if fabs(x)>1, O is returned, and math_errno is set to EDOM (domain error). 


See also 
sin(), acos(), atan(), atan2() 
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Math Library Functions 3-5 


atan 
Arctangent. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double atan( 
double x) Value whose arctangent is to be calculated 


Explanation 
Determines the arctangent of x. 


Return value 
Arctangent of x, ranging from -pi/2 to pi/2 radians. 


See also 
tan(), asin, acos(), atan2() 
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3-6 Math Library Functions 


atan2 
Arctangent. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double atan2( 
double x, double y) Floating-point values 


Explanation 
Determines the arctangent of x/y. If x and y are O, a value of O is returned. 


Return value 
Arctangent of x/y, ranging from -pi to pi. 


See also 
acos(), asin(), tan(), atan() 
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Math Library Functions 3-7 


atof 

Convert a string to a floating-point equivalent. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double atof( 

char *s) Pointer to a string 

Explanation 


Converts a string "s" to its floating-point (double type) equivalent. 


Return value 
The result from converting input string "s" to a double floating point equivalent. 
Error handling: if there is an overflow error, either +HUGE_VAL(1.797693134862316e+308) or -HUGE_VAL 


depending on the sign, is returned, and math_errno is set to ERANGE (range error). If there is an 
underflow, O is returned, and math_errno is set to ERANGE (range error). 


See also 
strtod() 
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3-8 Math Library Functions 


ceil 

Minimum integer not less than x (ceiling function). 
Library Header File Introduced Documentation Date 
libmath. lib liomath.h 3.0 12/14/98 

Syntax 

double ceil( 

double x) Floating-point value 

Explanation 





Determines the minimum integer (double type) not less than x. 


Return value 
Minimum integer (double type) not less than x. 


See also 
floor() 
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Math Library Functions 3-9 


cos 
Cosine. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double cos( 
double x) Angle in radians 


Explanation 
Determines the cosine of x. 


Return value 
Cosine of x (cos(x)). 


See also 
sind, tan), acos() 
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3-10 Math Library Functions 


cosh 
Hyperbolic cosine. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double cosh( 
double x) Angle in radians 


Explanation 
Determines the hyperbolic cosine of x. 


Return value 
Hyperbolic cosine of x (cosh(x)). 


See also 
sinh(, tanh() 
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Math Library Functions 3-11 


exp 
Exponent. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double exp( 
double x) Floating-point value 


Explanation 
Determines the exponential of x. 


Return value 
e raised to the x-th power (e**x). 


See also 
pow(), log(), Idexp() 
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3-12 Math Library Functions 


fabs 


Absolute value (macro). 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double fabs( 
double x) Floating-point value 


Explanation 
This macro determines the absolute value of a double. 


Return value 
Absolute value of x. 


See also 
abs (see lic), lals() (see libc) 
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Math Library Functions 3-13 


floor 

Maximum integer not more than x (lower function). 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double floor( 

double x) Floating-point value 

Explanation 


Determines the maximum integer (double type) not more than x. 


Return value 
Maximum integer not more than x (double type) 


See also 
ceil() 
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3-14 Math Library Functions 


fmod 

Floating-point remainder resulting from x/y. 
Library Header File Introduced Documentation Date 
libmath. lib libmath.h 3.0 12/14/98 

Syntax 

double fmod( 

double x, double y) Floating-point values 

Explanation 

Determines the floating-point remainder resulting from x/y. The sign of the return value is the same as that 

of x. 


Return value 
Floating-point remainder resulting from x/y. If y is O, O is returned. 


See also 
modf() 
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Math Library Functions 3-15 


frexp 

Resolve into a normalized fraction and a power of 2. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double frexp( 

double x, Floating-point value 

int *n) Pointer to the part that is a power of 2 

Explanation 


Resolves x into a fraction in the interval [1/2, 1) (that is, 1/2<= x < 1), and a power of 2. The fractional part is 
returned, and the power of 2 is stored inn. 


A pair of square brackets [] indicates a closed area, while a pair of parentheses () indicates an open area. 


Return value 
The normalized fraction. 
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3-16 Math Library Functions 


hypot 

Absolute value of a complex number. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double hypot( 

double x, double y) Floating-point values 

Explanation 


Computes the square root of the sum of the squares of x and y. 


Return value 
Square root of the sum of (x**2) and (y**2). 
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Math Library Functions 3-17 


Idexp 

Calculate a real number from a mantissa and an exponent. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double Idexp( 

double x, Floating-point value 

int n) Integral exponent 

Explanation 


Determines a real number from a mantissa and an exponent. 


Return value 
Value of x multiplied by 2 raised to the n” power. 
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3-18 Math Library Functions 


log 
Natural logarithm. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double log( 
double x) Value subjected to logarithmic operation 


Explanation 
Determines the natural logarithm of x. 


Return value 
Logarithm of x (In(x)) for x >0. 


Error handling: If x = 0, 1 is returned, and math_errno = ERANGE (range error). If x <0, O is returned, and 
math_errno = EDOM (domain error). 


See also 
exp(), log10() 
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log10 


Base 10 logarithm. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double log10( 
double x) Value subjected to logarithmic operation 


Explanation 
Determines the logarithm of x whose base is 10. 


Return value 
Logarithm of x whose base is 10 (log10(x)) 


x must be greater than zero. Otherwise, an error results: If x =0, 1 is returned, and math_errno = ERANGE 
(range error). If x <0, O is returned, and math_errno = EDOM (domain error). 


See also 
log() 
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3-20 Math Library Functions 


modf 

Separate a double into integral and fractional parts. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double modf( 

double x, Floating-point value 

double *y) Pointer to the integral part 

Explanation 


Separates x into integral and fractional parts. The integral part is stored in y, and the return value is the 
fractional part. The signs of both parts are the same as the sign of x. 


Return value 
Fractional part of x. 


See also 
fmod() 
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Math Library Functions 3-21 


pow 
Raise a double to a power. 
Library Header File Introduced Documentation Date 


lipmath.lib libmath.h 3.0 12/14/98 


Syntax 

double pow( 

double x, Floating-point value 
double y) Pointer to the integral part 
Explanation 

Raises x to the y-th power. 


Return value 
x raised to the y-th power(x**y). 











Table 3-1 
Condition Return value Error (math_errno) 
x==0 && y>0 (0) Domain error (EDOM) 
x==0 && y<=0 1 Domain error (EDOM) 
x<0 && [y not an integer] 0 Domain error (EDOM) 

See also 

exp(), sqrt() 
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3-22 Math Library Functions 


printf2 

Convert formatted output as standard output (with floating-point and double-precision arguments). 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 2/24/99 

Syntax 

int printf2( 


const char *fmtf,argument...]) — Pointer to input format character string 


Explanation 
The conversion directives [f] [e] [E] [g] and [G] can be used. 


Stack consumption is greater than with printf(). 


Note: When printf() (or printf2(), putchar(), or puts()) is being executed in the main flow, and an interrupt 
occurs, text corruption or a hang-up can result if printf) is called during the interrupt. Therefore, pay 
attention to the call timing when calling printf() in an interrupt. 


Return value 
Output character length. 


See also 
sprintf2() 
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Math Library Functions 3-23 
sin 
Sine. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double sin( 
double x) Angle in radians 


Explanation 
Determines the sine of x. 


Return value 
Sine of x (sin(x)). 


See also 
cos(), tan(), asin() 
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3-24 Math Library Functions 


sinh 
Hyperbolic sine. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double sinh( 
double x) Angle in radians 


Explanation 
Determines the hyperbolic sine of x. 


Return value 
Hyperbolic sine of x (sinh(x)). 


See also 
cosh(), tanh() 
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Math Library Functions 3-25 


sprintf2 

Format output to a string (with floating-point and double-precision arguments). 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

int sprintf2( 

char *s, Pointer to destination string 


const char *fmt[{,argument...]) Pointer to input format character string 


Explanation 
The conversion directives [f] [e] [E] [g] and [G] can be used. 


Stack consumption is greater than with sprintf. 


Return value 
Output character length. 


See also 
printf2() 
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3-26 Math Library Functions 


sqrt 
Square root. 


12/14/98 Header File Introduced Documentation Date 
liomath. lib lipmath.h 3.0 12/14/98 


Syntax 


double sqrt( 
double x) Non-negative floating-point value 


Explanation 
Determines the non-negative square root of x. 


Error processing: if x<O, zero is returned, and math_errno = EDOM (domain error). 


Return value 
Square root of x. 


See also 
pow() 
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Math Library Functions 3-27 


strtod 

Convert a string to a floating-point equivalent. 
Library Header File Introduced Documentation Date 
liomath.lib liomath.h 3.0 12/14/98 

Syntax 

double strtod( 

char *s, Input string 

char **endp) Pointer to a string that was unable to be converted (output) 

Explanation 


Converts a string to a double type floating-point equivalent. 


s must be one of the following: 


[ws][sn][ddd] 

[ws] White space (may be omitted) 
[sn] Sign (may be omitted) 

[ddd] Number string (may be omitted) 


Stops converting upon encountering a character that was unable to be converted. If endp is not NULL, the 
pointer to the character in error is set to endp. 


Return value 
The result from converting s to a floating point double type. 
Error handling: if the converted value overflows, either +HUGE_VAL(1.7976931 348623 16e+308) or - 


HUGE_VAL according to the sign, is returned. O is returned for an underflow case, or if no conversion could 
be performed. In either case, math_errno = ERANGE (range error). 











See also 
atof() 
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3-28 Math Library Functions 


tan 
Tangent. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 
double tan( 
double x) Angle in radians 


Explanation 
Determines the tangent of x. 


Return value 
Tangent of x (tan(x)). 


See also 
sinf, cos(), atan(), atan2() 
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Math Library Functions 3-29 


tanh 
Hyperbolic tangent. 


Library Header File Introduced Documentation Date 
liomath. lib liomath.h 3.0 12/14/98 


Syntax 


double tanh( 
double x) Angle in radians 


Explanation 
Determines the hyperbolic tangent of x. 


Return value 
Hyperbolic tangent of x (tanh(x)). 


See also 
sinh(), cosh() 
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Memory Card Library Functions 4-3 


InitCARD 
Initialize Memory Card BIOS. 


Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 


Syntax 


void InitCARD( 
long val) Specify sharing with controller 


Explanation 
Initializes the Memory Card BIOS and enters an idle state. val specifies whether or not there is sharing with 
the controller. (0: not shared; 1: shared.) 





When the BIOS is subsequently put into operation by StartCARD(), the low-level interface functions that 
begin with “_card” can be used directly. 





The Memory Card file system uses these interfaces internally, so InitCARD() needs to be executed before 
_bu_init(. 


There is no effect on the controller. 





See also 
_bu_init( 
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4-4 Memory Card Library Functions 


StartCARD 
Start Memory Card BIOS. 


Library Header File Introduced Documentation Date 
liocard.lib libapi.h 3.0 12/14/98 


Syntax 
void StartCARD(voic) 


Explanation 
Changes the Memory Card BIOS initialized by InitCARD() to a run state. 


Performs ChangeClearPAD(1) internally. 


See also 
InitCARD(), StopCARD(, _bu_init(), ChangeClearPAD() (see libapi) 
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Memory Card Library Functions 4-5 


StopCARD 
Stop Memory Card BIOS. 


Library Header File Introduced Documentation Date 
libcard. lib libapi.h 3.0 12/14/98 

Syntax 

void StopCARD(voia) 

Explanation 


Changes Memory Card BIOS to an idle state--the same state as that immediately after executing 
InitCARD(). 





It also stops the controller. It is necessary to call StartPAD( to start the controller. 


See also 
InitCARD(), StartCARD(), _bu_init(), ChangeClearPAD() (see libapi) 
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4-6 Memory Card Library Functions 


_bu_init 
Initialize Memory Card file system. 


Library Header File Introduced Documentation Date 
liocard.lib libapi.h 3.0 12/14/98 


Syntax 
void_bu_init(void) 


Explanation 


Initializes the Memory Card file system. This file system is not initialized automatically, so it is necessary to 
call this function. 


See also 
InitCARD(), StartCARD(, StopCARD() 
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Memory Card Library Functions 4-7 


_card_auto 

Set automatic format function. 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_auto( 

long val) Indicates automatic formatting 

Explanation 


When val is O, the automatic format function is disabled; when val is 1, it is enabled. 


This function should be used for testing purposes only. 


Return value 
Previously set automatic format value. 
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4-8 Memory Card Library Functions 


_card_chan 

Get a Memory Card BIOS event. 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 


long _card_chan(voic) 


Explanation 
Returns the device number of the Memory Card that just generated an event. 








Return value 
2-digit hex device number. 





See also 
card_status(), _card_wait() 
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Memory Card Library Functions 4-9 


_card_clear 
Clear unconfirmed flags. 


Library Header File Introduced Documentation Date 
liocard.lib libapi.h 3.0 12/14/98 


Syntax 

long _card_clear( 

long chan) Port number x 16 + Card number 
Explanation 


Performs a dummy write to the system management area of the card and clears the card’s unconfirmed 
flags. 





When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card number” is zero when a 
standard controller is connected, and may be in the range O-3 if a Multi Tap is connected. 


This function executes asynchronously, so it returns immediately. Processing completion is communicated 
by an event. (See table below.) In order to use this command with multiple slots in a Multi Tap, you must 
wait until processing has completed before sending another _card_clear() call. 


Table 4-1: Events on completion of processing 








Source Descriptor/Event Class Contents 
HwCARD/EvSplOE Ends process 
HwCARD/EvSpTIMOUT Card not connected 
HwCARD/EvSpNEW New card detected 
HwCARD/EvSpERROR Error generated 
HwCARD/EvSpUNKOWN Source unknown 





Return value 
1 if registration successful, otherwise O. 


See also 
card_info() 
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4-10 Memory Card Library Functions 


_card_format 
Format the Memory Card. 


Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_format( 

long chan) Port number x 16 + Card number 

Explanation 


Formats the Memory Card. When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card 
number” is zero when a standard controller is connected, and may be in the range 0-3 if a Multi Tap is 
connected. 


Does not enter critical section. Synchronous functions are blocked for approximately 144 Vsync. 


Return value 
1 if formatting is successful, otherwise 0. 


See also 
_card_load() 
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Memory Card Library Functions 


_card_info 
Get card status. 


Library Header File Introduced Documentation Date 
liocard.lib libapi.h 3.0 12/14/98 


Syntax 

long _card_info( 

long chan) Port number x 16 + Card number 
Explanation 

Tests the connection of the Memory Card specified in chan. 


When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card number” is zero when a 
standard controller is connected, and may be in the range O-3 if a Multi Tap is connected. 


This function executes asynchronously, so it returns immediately. Processing completion is communicated 
by an event. (See table below.) In order to use this command with multiple slots in a Multi Tap, you must 
wait until processing has completed before sending another _card_info() call. 


Table 4-2: Posts an event on completion of processing 








Source Descriptor/Event Class Description 
SwCARD/EvSplOE Connected 
SwCARD/EvSpTIMOUT Not connected 
SwCARD/EvSpNEW No writing after connection 
SwCARD/EvSpERROR Generates an error 





Do not use _new_card() to suppress EvSpNEW. 


Return value 
1 if registration successful, otherwise O. 


See also 
card_clear(), _card_status(), _new_card() 
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_card_load 
Test logical format 


Library Header File Introduced Documentation Date 
liocard.lib libapi.h 3.0 12/14/98 


Syntax 


long _card_load( 
long chan) Port number x 16 + Card number 


Explanation 
Reads file management information for the card specified by chan in the file system in order to get 
asynchronous access using the I/O management service. 


When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card number” is zero when a 
standard controller is connected, and may be in the range O-3 if a Multi Tap is connected. 


_card_load() must be called at least once before you can use open() on a Memory Card file in O_NOWAIT 
mode. It does not have to be called again unless a card is changed. 


This function executes asynchronously, so it returns immediately. Processing completion is communicated 
by an event. (See table below.) In order to use this command with multiple slots in a Multi Tap, you must 
wait until processing has completed before sending another _card_load\() call. 





Table 4-3: Posts an event on completion of processing 








Source Descriptor/ Event Class Contents 
SwCARD/EvSplOE Read completed 
SwCARD/EvSpTIMOUT Not connected 
SwCARD/EvSpNEW Uninitialized card 
SwCARD/EvSpERROR Generates an error 





Return value 
1 if the read is successful, otherwise O. 


See also 
format() (see libcd), card_info() 
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_card_read 

Read one block from the Memory Card. 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_read( 

long chan, Port number x 16 + card number 

long block, Target block number 

long *buĥ Pointer to 128 byte data buffer 

Explanation 


Reads 128 bytes of buffer data into buf from the target block number (block) of the Memory Card of the 
specified channel (chan). 


When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card number” is zero when a 
standard controller is connected, and may be in the range O-3 if a Multi Tap is connected. 


This function executes asynchronously so it returns immediately after completion. Actual processing 
termination is communicated by an event. (See table below.) Multiplex processing to the same card slot 
can’t be performed. 


Table 4-4: Events on completion of processing 








Source Descriptor / Event Class Contents 
HwCARD/EvSplOE Ends processing 
HwCARD/EvSpTIMOUT Card not connected 
HwCARD/EvSpNEW New card detected 
HwCARD/EvSpERROR Error generated 
HwCARD/EvSpUNKOWN Source unknown 








This function exists within the low-level interface and is one of the special functions used for testing. 


Return value 
1 if successful processing registration, otherwise O. 


See also 
_card_write(), open() (See libapi), read() (see libapi) 
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_card_status 
Get Memory Card BIOS status. 


Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_status( 

long arv) Port number 

Explanation 


Gets the Memory Card BIOS status of each slot, drv. Specify drv as O for Port 1, 1 for Port 2. 


This is a synchronous function. 


Return value 
If the Memory Card BIOS is in run state, it can return any of the following values. 











Table 4-5 
Value State 
Ox01 Idle processing 
0x02 READ processing 
0x04 WRITE processing 
0x08 Connection test processing registration 
0x11 No registered processing (just prior to 
EvSpTIMOUT generation) 
0x21 No registered processing (just prior to 
EvSpERROR generation) 
See also 


card_wait(), _card_chan(), _card_info() 
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_card_wait 

Wait for Memory Card BIOS completion. 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_wait( 

long arv) Sets slot number 

Explanation 


Wait until registration processing completes for the drv slot. Specify drv as O for Port 1, 1 for Port 2. 


Return value 
Always 1. 


See also 
_card_status(), _card_chan() 


CONFIDENTIAL Run-Time Library Reference 


4-16 Memory Card Library Functions 


_card_write 

Write to one block of the Memory Card (for testing only) 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 

long _card_write( 

long chan, Port number x 16 + card number 

long block, Target block number 

long *buĥ Pointer to 128-byte data buffer 

Explanation 


Writes 128 bytes of buffer data pointed to by buf to the target block number (block) of the Memory Card of 
the specified channel (chan). 


When calculating chan, “port number” is O for Port 1 and 1 for Port 2. “Card number” is zero when a 
standard controller is connected, and may be in the range 0-3 if a Multi Tap is connected. 


This function executes asynchronously, so it returns immediately. Actual processing termination is 
communicated by an event. (See table below.) Multiplex processing to the same card slot can’t be 
performed; that is, multiple _card_write() calls to the same Multi Tap cannot be processed synchronously. 





Table 4-6: Events on completion of processing 








Source Descriptor/Event Class Contents 
HwCARD/EvSplOE Ends process 
HwCARD/EvSpTIMOUT Card not connected 
HwCARD/EvSpNEW New card detected 
HwCARD/EvSpERROR Error generated 
HwCARD/EvSpUNKOWN Source unknown 





This is a low-level function that should be used for testing only. It bypasses the memory card file system; 
therefore, in a released product, use the C file-handling routines such as write(). 


Return value 
1 if registration successful, otherwise O. 


See also 
_card_read(), open() (see libapi), write() (see libapi) 
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_new_card 

Change settings of unconfirmed flag test. 
Library Header File Introduced Documentation Date 
libcard.lib libapi.h 3.0 12/14/98 

Syntax 


void _new_card(void) 


Explanation 
Masks the generation of an EvSpNEW event immediately after _card_read() or _card_write(). 


Terminates immediately even though it is a synchronous function. 





See also 
card_clear(), _card_read(), _card_write() 
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MemCardAccept 
Check Memory Card status. 


Library Header File Introduced Documentation Date 
liomcrd.lib liomcrd.h 4.0 12/14/98 


Syntax 

long MemCardAccept( 

long chan) port number + card number 
port number(port A: 0x00; port B: 0x10) 
card number (normally 0) 


Explanation 
Tests connection with the Memory Card specified by chan. If the card is connected, additional information 


is obtained. If the card is new, _card_clear() and _card_load() are executed, allowing the use of file access 
functions. 


MemCardAccept() must be executed before using file access functions such as MemCardOpen(). 
MemCardAccept() does not need to be called again as long as the card is not swapped. 





The function is asynchronous and returns immediately. (Multiple instances can’t be registered.) Use 
MemCardSync( or an exit callback to determine completion and get the result, which is one of the 
following: 








Table 5-1 

Value Macro Status 

0x00 McErrNone Connected 

0x01 McErrCardNotExist Not connected 

0x02 McErrCardlnvalid Bad card 

0x03 McErrNewCard New card (card was 
replaced) 

0x04 McErrNotFormat Not formatted 





The maximum time required to perform this operation is 76 VSyncs. Approximately 4 VSyncs are needed if 
a card is not present. 


A new card is detected only once and returns McErrNewCard. Subsequent calls return McErrNone. 


Return value 
1 if registration successful, otherwise O. 


See also 
MemCardOpen(), MemCardReadFile(), MemCardWriteFile), MemCardExist() 
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MemCardCallback 

Define exit callback. 
Library Header File Introduced Documentation Date 
liomerd.lib liomerd.h 4.0 12/14/98 

Syntax 

MemCB MemCardCallback( 

MemCB func) pointer to callback function 

Explanation 


Sets the callback function (func) to be triggered when an asynchronous function completes. If func is O, no 
callback is generated. 


The following format is used for exit callback functions: 


typedef void (*MemCB)( unsigned long cmds, unsigned long result ) 
cmds: the completed asynchronous function (see below) 
result: the execution result from the asynchronous function 


Allowed value for cmas: 








Table 5-2 
Value Macro Function 
0x01 McFuncExist MemCardExist 
0x02 McFuncAccept MemCardAccept 
0x03 McFuncReadFile MemCardReadFile 
0x04 McFuncWriteFile MemCardWriteFile 
0x05 McFuncReadData MemCardReadData 
Ox06 McFuncWriteData MemCardWriteData 





See the sections on the respective functions for details of the result value. 


Return value 
The address of the previously set callback. 





See also 
MemCardAccept(), MemCardExist(), MemCardReadFile(), MemCardWriteFile(), MemCardReadData\(), 
MemCardWriteData(), MemCardSync() 
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MemCardClose 


Close file. 


Library Header File Introduced Documentation Date 
liomerd. lib liomerd.h 4.0 12/14/98 


Syntax 
void MemCardClose(voia) 


Explanation 
Closes the file that was opened with MemCardOpen(). It is an asynchronous function that exits 
immediately. 


See also 
MemCardOpen() 
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MemCardCreateFile 

Create a new file in the Memory Card 
Library Header File Introduced Documentation Date 
libmcrd.lib liomerd.h 4.0 12/14/98 

Syntax 

long MemCardCreateFile( 

long chan, port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 


char “file, filename 
long blocks) number of blocks 
Explanation 


Creates the specified file in the Memory Card. It is a synchronous function; blocking time is 1 - 4 VSyncs for 
normal exit, 4 - 76 VSyncs otherwise. It doesn’t enter a critical section. 





The block parameter is given in units of 8192 bytes. 


Return value 











Table 5-3 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Card is not connected 
0x02 McErrCardlnvalid Communication error 
generated 
0x04 McErrNotFormat Not formatted 
Ox06 McErrAlreadyExist File already exists 
0x07 McErrBlockFull Not enough available 
blocks 
-1 None A non-synchronous 
function is active. 
See also 


MemCardOpen(), MemCardWriteFile(), MemCardDeleteFile() 
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MemCardDeleteFile 

Delete file from Memory Card. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomcrd.h 4.0 2/24/99 

Syntax 

long MemCardDeleteFile( 

long chan, port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 
char “file) filename 


Explanation 
Deletes the specified file from the Memory Card. It is a synchronous function; blocking time: 1 - 4 VSyncs 
for normal exit. 4 - 76 VSyncs otherwise. Does not enter critical section. 


Return value 








Table 5-4 

Value Macro Status 

Ox00 McErrNone Normal exit 

0x01 McErrCardNotExist Card is not connected 

0x02 McErrCardlnvalid Communication error 
generated (*1) 

0x04 McErrNotFormat Not formatted 

0x05 McErrFileNotExist File not found 

-1 None A non-synchronous 


function is active. 
(1: The same error code is also returned if the deleted file was an active PDA application. Because of the 
PDA kernel locking mechanism, the active PDA application cannot be deleted. 








See also 
MemCardCreateFile() 
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MemCardEnd 


Terminate Memory Card system. 


Library Header File Introduced Documentation Date 
liomerd. lib liomerd.h 4.0 12/14/98 


Syntax 
void MemCardEnd(voic) 


Explanation 
Terminates the Memory Card system. It is a synchronous function. 


MemCardStop() needs to be executed first if the system was activated from MemCardStart(). 


See also 
MemCardlnit(), MemCardStart(), MemCardStop() 
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MemCardExist 

Get connection status of card. 
Library Header File Introduced Documentation Date 
liomerd.lib liomerd.h 4.0 12/14/98 

Syntax 

long MemCardExist( 

long chan) port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 


Explanation 

Tests the connection status of the Memory Card specified by chan. MemCardExist( is faster than 
MemCardAccept(), since it checks only the presence of the card. MemCardAccept() must be used for more 
detailed information, such as whether the card is formatted. If cards are swapped, MemCardAccept() must 
be executed before using file access functions such as MemCardOpen(). 








The function is asynchronous and exits immediately. Multiple instances of the function cannot be 
registered. Use MemCardSync() or an exit callback to determine completion and obtain the result of the 
operation, as shown below: 











Table 5-5 
Value Macro Status 
0x00 McErrNone Connected 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Bad card 
0x03 McErrNewCard New card (card was 
replaced) 





The time required is approximately 4 VSyncs. 


When a new card is detected (McErrNewCard), you must call MemCardAccept() to clear the new card 
status, before performing any other operations. 


Return value 
1, if the command was successfully registered; O otherwise. 


See also 
MemCardAccept() 
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MemCardFormat 


Format Memory Card. 


Library Header File Introduced Documentation Date 
liomerd. lib liomerd.h 4.0 12/14/98 


Syntax 

long MemCardFormat( 

long chan) port number + card number 
port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 


Explanation 
Formats the specified Memory Card. Synchronous function. Blocking time: approx. 144 VSyncs. Does not 
enter critical section. 


Return value 











Table 5-6 
Value Macro Status 
0x00 McErrNone Connected 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Communication error 
-1 None A non-synchronous 
function is active 
See also 
MemCardUnformat() 
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MemCardGetDirentry 

Get directory information from Memory Card. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomerd.h 4.0 2/24/99 

Syntax 

long MemCardGetDirentry( 

long chan, port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 








char *name, filename to be searched (wildcards can be used) 

struct DIRENTRY “oir, pointer to structure to hold information about matching files 

long “files, pointer to buffer to hold number of matching files 

long ofs, offset for entry. Specifies the number of files to skip from the first file that 
matches before saving to the buffer (O - 14). 

long max) maximum number of entries to store in the buffer 

Explanation 





Finds files matching the filename pattern name. Data for these files are stored in dir, and the total number of 
matching files is returned in files. The buffer must be prepared by the user application. 





Synchronous function. Blocking time: 1 - 2 VSyncs for normal exit. Otherwise, 4 - 76 VSyncs. 


Wildcard characters can be used in the filename pattern: "?" for any single character; "*" for any number of 
characters. Characters following * are ignored. 





Return value 








Table 5-7 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Card is not connected 
0x02 McErrCardlnvalid Bad card 
-1 None A non-synchronous 


function is active. 





CONFIDENTIAL Run-Time Library Reference 


5-12 Extended Memory Card Library Functions 


MemCardlinit 

Initialize Memory Card system. 
Library Header File Introduced Documentation Date 
libmcrd.lib liomerd.h 4.0 12/14/98 

Syntax 

void MemCardinit( 

long vai) Use of control routine in ROM (0: do not use, 1: use) 

Explanation 


Initializes the Memory Card system. If the system is subsequently activated with MemCardStart(), libmerd 
functions (those beginning with "MemCard") are available. MemCardlnit() should be executed after 
InitPAD(, InitGUNQ, or InitTAP(). 


val should be set to O when using libtap or lilbgun. 


MemCardlnit() requires 60 - 70 VSyncs to complete. It cannot be executed twice. 





See also 
MemCardEnd(), MemCardStart(), MemCardStop() 
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MemCardOpen 
Open file. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomerd.h 4.0 12/14/98 
Syntax 
long MemCardOpen( 
long chan, port number + card number 
port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 
char “file, filename 
long flag) specifies method with which to open 
(read only: O_LRDONLY, write only: O_WRONLY) 
Explanation 





Opens the specified Memory Card file with the method specified by flag. Once the file is open, 
MemCardReadData() and MemCardWriteData() can be used. 


Methods cannot be combined (O_RDONLYIO_WRONLY). Multiple files cannot be opened. 


Synchronous function. Blocking time: Exits immediately for normal completion. Otherwise, 4 - 76 VSyncs. 


Return value 











Table 5-8 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Card is not connected 
0x02 McErrCardlnvalid Bad card 
0x04 McErrNotFormat Not formatted 
0x05 McErrFileNotExist File not found 
-1 None Either another file is already 
open or a non- 
synchronous function is 
active in the background. 
See also 


MemCardReadData(), MemCardWriteData(), MemCardClose() 
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MemCardReadData 

Read data from Memory Card. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomerd.h 4.0 12/14/98 

Syntax 

long MemCardReadData( 

unsigned long “aars, pointer to destination buffer in main memory 

long offset, offset in bytes from which to read, where the start of the file is defined to 

be O 
long bytes) number of bytes to read (multiple of 128) 
Explanation 


Reads data from the Memory Card file previously opened in MemCardOpen\() and stores it in the buffer 
pointed to by adrs. 


It is an asynchronous function and exits immediately. Multiple instances cannot be registered. 


Use MemCardSync() or an exit callback to determine completion and obtain the result of the operation. 
(The time required is approximately 1 VSync overhead + approximately 130 VSyncs per block (8192 bytes). 


bytes is specified in units of 128. If anumber that is not a multiple of 128 is specified, the process is not 
registered and the operation terminates with a return value of O. 





The function result can have the values shown below. 








Table 5-9 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Communication error 
0x03 McErrNewCard New card (card swapped) 





Return value 
1 if operation was registered successfully. Otherwise, O. 


See also 
MemCardOpen(), MemCardSync() 
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MemCardReacFile 

Read file from Memory Card. 
Library Header File Introduced Documentation Date 
liomerd.lib liomerd.h 4.0 12/14/98 

Syntax 

long MemCardReadFile( 

long chan, port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 


char “file, filename 

unsigned long “aars, pointer to destination buffer in main memory 

long offset, offset in bytes from which to read, where the start of the file is defined to 
be O 

long bytes) number of bytes to read (multiple of 128) 

Explanation 


Reads data from the specified Memory Card file and stores it in the buffer pointed to by adrs. bytes is 
specified in units of 128. If a number that is not a multiple of 128 is specified, the process is not registered 
and the operation terminates with a return value of O. 











This function is asynchronous and returns immediately. Multiple instances cannot be registered. Use 
MemCardSync() or an exit callback to determine completion and obtain the result of the operation, as 
shown below. 








Table 5-10 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Communication error 
0x03 McErrNewCard New card (card swapped) 
0x05 McErrFileNotExist File cannot be found 





Required time: approximately 1 VSync overhead + approximately 130 VSyncs per block (8192 bytes). 


MemCardOpen() and MemCardReadData() are executed within MemCardReadFile(). If MemCardOpen( is 
executed on a file which is already open, an error is generated and the value O is returned. 





Return value 


1 if operation was registered successfully. If the file was already open, or another asynchronous function 
was already registered, O is returned. 





See also 
MemCardOpen(), MemCardReadFile(), MemCardSync() 
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MemCardStart 


Start Memory Card system. 
Library Header File Introduced Documentation Date 
libmcrd.lib libmcrd.h 4.0 12/14/98 


Syntax 
void MemCardStart(void) 


Explanation 
Places the Memory Card system, previously initialized with MemCardlnit() in an active state. Internally, eight 
events such as HwCARD and SwCARD are opened. 





Asynchronous Function. Exits immediately. 


See also 
MemCardlnit(), MemCardStop() 
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MemCardStop 
Stop Memory Card system. 


Library Header File Introduced Documentation Date 
liomerd. lib liomerd.h 4.0 12/14/98 


Syntax 
void MemCardStop(voic) 


Explanation 
Stops the Memory Card system activated by MemCardStart(). Various events are closed. 


Asynchronous Function. Exits immediately. 


See also 
MemCardlnit(), MemCardStart(), MemCardStop() 
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MemCardSync 
Wait for completion of an asynchronous function or check status. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomerd.h 4.0 12/14/98 
Syntax 
long MemCardSync( 
long mode, O: wait for termination of asynchronous function 
1: check current status and return immediately 
long *cmds, pointer to the terminated asynchronous function 
long *result) pointer to execution results from the asynchronous function 
Explanation 


If mode is O, this function waits for termination of an asynchronous function such as MemCardAccept() and 
MemCardReadFile(). The execution time depends on the corresponding asynchronous function. 





If mode is 1, it exits immediately and returns the status of the asynchronous function (see Return value). 


cmds stores the operation code corresponding to the terminated asynchronous function: 








Table 5-11 
Value Macro Function 
0x01 McFuncExist MemCardExist 
0x02 McFuncAccept MemCardAccept 
0x03 McFuncReadFile MemCardReadFile 
0x04 McFuncWriteFile MemCardWriteFile 
0x05 McFuncReadData MemCardReadData 
Ox06 McFuncWriteData MemCardWriteData 





Return value 

0: — Still active 

1: Terminated 

-1: No registered process 


See also 


MemCardAccept(), MemCardExist(), MemCardReadFile(), MemCardWriteFile(), MemCardReadData(), 
MemCardWriteData(), MemCardCallback() 


Run-Time Library Reference CONFIDENTIAL 


Extended Memory Card Library Functions 5-19 


MemCardUnformat 

Uninitialize a Memory Card (for debugging only). 
Library Header File Introduced Documentation Date 
liomcrd.lib liomerd.h 4.3 12/14/98 

Syntax 

long MemCardUnformat( 

long chan) port number + card number 


port number (port A: 0x00, port B: 0x10) 
card number (default 0) 
Explanation 
Puts Memory Card in uninitialized (unformatted) state. Synchronous function. 
MemCardUnformat() is a debugging function that can be used to create an unformatted card. This function 


should only be used for testing Memory Card initialization during program debugging. It should not be used 
in an actual title. 





Return value 
1: Completed successfully. O: Error. -1: Could not be executed because of an asynchronous function 
running in the background. 


See also 
MemCardFormat() 
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MemCardWriteData 

Write data to Memory Card. 
Library Header File Introduced Documentation Date 
liomcrd.lib liomcrd.h 4.0 8/9/99 

Syntax 

long MemCardWriteData( 

unsigned long “aars, pointer to destination buffer in main memory 

long offset, offset in bytes from which to write, where the start of the file is defined to 

be O 

long byte) number of bytes to write (multiple of 128) 

Explanation 

Writes data from the buffer pointed to by adrs to the Memory Card file previously opened with 

MemCardOpen(). 


MemCardWriteData() is asynchronous and exits immediately. Multiple instances cannot be registered. 
Required time: Approximately 1 VSync overhead + 130 VSyncs per block (8192 bytes) 


Use MemCardSync() or an exit callback to determine completion and obtain the result of the operation. 


bytes is specified in units of 128. If anumber that is not a multiple of 128 is specified, the process is not 
registered and the operation terminates with a return value of O. 





The function result can have the values shown below. 








Table 5-12 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Communication error 
0x03 McErrNewCard New card (card swapped) 





Return value 
1 if the operation was registered successfully, O otherwise. 


See also 
MemCardOpen(), MemCardSync() 
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MemCardWriteFile 
Write file to Memory Card. 


Library Header File Introduced Documentation Date 
liomerd. lib liomerd.h 4.0 8/9/99 


Syntax 

long MemCardWriteFile( 

long chan, port number + card number 
port number (port A: 0x00, port B: 0x10) 
card number (normally 0) 





char “file, filename 

unsigned long “aars, pointer to destination buffer in main memory 

long offset, offset in bytes from which to write, where the start of the file is defined to 
be O 

long bytes) number of bytes to write (multiple of 128) 

Explanation 


Writes data from the buffer pointed to by adrs to the specified Memory Card. If the file is new, it must be 
created beforehand with MemCardCreateFile(). bytes is specified in units of 128. If a number not a multiple 
of 128 is specified, the process is not registered and the operation terminates with a return value of O. 





MemCardWriteFile() is an asynchronous function and returns immediately. Multiple instances cannot be 
registered. Use MemCardSync() or an exit callback to determine completion and obtain the result of the 
operation, as shown below: 





The function result can have the values shown below. 








Table 5-13 
Value Macro Status 
Ox00 McErrNone Normal exit 
0x01 McErrCardNotExist Not connected 
0x02 McErrCardlnvalid Communication error 
0x03 McErrNewCard New card (card swapped) 
0x05 McErrFileNotExist File not found 





Required time: Approximately 1 VSync overhead + 130 VSyncs per block (8192 bytes). 


MemCardOpen() and MemCardWriteData() are executed within MemCardWriteFile(). If MemCardOpen() is 
executed on a file which is already open, an error is generated and the value O is returned. 





Return value 


1 if operation was registered successfully. If the file was already open, or another asynchronous function 
was already registered, O is returned. 








See also 
MemCardCreateFile(), MemCardSync() 
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DECDCTENV 
Quantization tables used during MDEC decoding process. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.5 12/14/98 
Structure 
typedef struct { 
u_char ig_y/64]; Brightness component quantization table 
u_char ig_c/64]; Chrominance component quantization table 
short dct/64]; System reserved 
} DECDCTENV; 
Explanation 


This structure contains the tables used during the reverse-quantization step of the MDEC decoding 
process. The default values used by the system are: 


iq y 





2 16 19 22 26 27 -29 34 ] 
16 16 22 24 «427 29 «34 37 
19 22 26 27 £42.29 34 34 38 
22 22 26 27 29 34 37 40 | x 
1/16 
22 26 27 29 32 35 40 48 
26 27 29 32 35 40 48 58 
26 27 29 34 38 46 56 69 

| 27 29 35 38 46 56 69 83 ] 

iq c 

2 16 19 22 26 27 #229 34 ] 
16 16 22 24 27 29 «34 = 37 
19 22 26 27 £42.29 34 34 38 
22 22 26 27 «229 34 «37 + «40 | x 
1/16 
22 26 27 29 32 35 40 48 
26 27 29 32 35 40 48 58 
26 27 29 34 38 46 56 69 

| 27 29 35 38 46 56 69 83 ] 


The values in the iq_y and iq_c tables are sorted in a diagonal zig-zag scanning order. 
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ENCSPUENV 
SPU encode environment attribute structure. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.6 8/27/99 
Structure 
typedef struct { 
short “src; 16-bit PCM data address 
short “dest; PlayStation® original waveform data 
short *work; Work area when encode processing 
long size; 16-bit PCM data size(in bytes) 
long /oop_start; PCM data loop start point(in bytes) 
char /oop; Loop waveform generation specification 


ENCSPU_ENCODE_LOOP: Generate loop waveform data 
ENCSPU_ENCODE_NO_LOOP: Generate non-loop waveform data 

char byte_swap; PCM data endian specification 
ENCSPU_ENCODE_ENDIAN_BIG: 16-bit big endian 
ENCSPU_ENCODE_ENDIAN_LITTLE: 16-bit little endian 

char proceed; Whole/Divided encoding specification 
ENCSPU_ENCODE_WHOLE: Whole encoding 
ENCSPU_ENCODE_START: Start divided encoding 
ENCSPU_ENCODE_CONTINUE: Continue divided encoding 
ENCSPU_ENCODE_END: End divided encoding 
Encoding quality. Only effective for EncSPU2(). 
Specify either ENCSPU_ENCODE_MIDDLE_QUALITY or 
ENCSPU_ENCODE_HIGH_QUALITY. 

char pad4; System reserved 

} ENCSPUENV; 


Explanation 
This structure is used to specify the SPU encode environment attributes for EncSPU() function. 


When ENCSPU_ENCODE_NO_LOOP is specified for loop, loop_start is ignored. 


See also 
EncSPU() 
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DecDCTBufSize 

Get size of run-level DCT data. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2x 12/14/98 

Syntax 

long DecDCTBufSize( 

u_long *bs) Pointer to bitstream 

Explanation 


Returns the uncompressed length of the data contained in the Huffman-encoded bitstream pointed to by 
the bs parameter. It does not perform the actual decoding. 


When using DecDCTvic()/DecDCTvlc2() to perform decoding, you must reserve a 1-word header buffer to 
add to the size obtained by this function. 


Return value 
Length of uncompressed data in long words (i.e. returns 1000 for a 4000-byte length). 


See also 
DecDCTvic(), DecDCTvic2() 
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DecDCTGetEnv 

Get current quantization tables and environment data used during MDEC image decoding. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.5 12/14/98 

Syntax 

DECDCTENV *DecDCTGetEnv( 

DECDCTENV “env) Pointer to decoding environment 

Explanation 


Returns the current decoding environment to env. 


Return value 
Address of env. 


See also 
DecDCTPutEnv() 
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DecDCTin 

Begin decoding RLE-encoded MDEC image data. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 


void DecDCTin( 
unsigned long *runievel, Pointer to input runlevel 
long mode) Decode mode 


Explanation 
Begins decoding the RLE-encoded MDEC image data at the address specified by runlevel. A maximum of 
128k may be decoded at atime. The resulting image data is retrieved by the DecDCTout() function. 


Bit O of the mode parameter controls the depth of the output pixels: O = 16-bit direct color; 1 = 24-bit 
direct color. In 16-bit mode, bit 1 of mode is the STP bit that determines bit 15 of the pixel. 


The image data produced is raw pixel data without any header information. The width and height of the 
image is not maintained; the application or a higher level structure (such as the STR format) must maintain 
such information. 


Data decoded from a single DecDCTin() call may be read using multiple DecDCTout() calls, or the data 
created by multiple DecDCTin( calls may be read using a single DecDCTout() call. 


DecDCTin() is non-blocking. To detect when execution of the primitive list is complete, use DecDCTinSync() 
or install a callback routine with DecDCTinCallback(). If DecDCTin() is called before a previous DecDCTin() 
operation has finished, it is blocked until the previous operation is complete. 





See also 
DecDCTout(), DecDCTinSync(), DecDCTinCallback() 
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DecDCTinCallback 

Install a callback routine to be called at termination of MDEC transmission. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

long DecDCTinCallback( 

void (*func)()) Pointer to callback function 

Explanation 


Installs the user-defined callback routine specified by func. This routine is called when the data transmission 
initiated by a DecDCTin() call has been completed. If func is O, any previous callback routine is disabled. 


Although the callback is called during an interrupt, it is not an interrupt handler; it should be written as a 
normal subroutine that is called by the main interrupt handler. Inside the callback, subsequent termination 
interrupts are masked; therefore, the callback should return as soon as possible. 


Return value 
A pointer to a previously set callback function. 


See also 
DecDCTin() 
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DecDCTinSync 

Detect DecDCTin() termination. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

long DecDCTinSync( 

long mode) O: Blocks until termination; 1: Performs only status notification 

Explanation 


Detects termination of DecDCTin(. 


Synchronization with DecDCTinSync()must be performed after reading the appropriate amount of decode 
data with DecDCTout(). When calling this function without using DecDCTout() after DecDCTin(), a timeout 
occurs and MDEC is reset. 


Return value 


Image processing subsystem status: 1 if transmission is in process and 0 if transmission is not being 
performed. 


See also 
DecDCTin(), DecDCTout() 
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DecDCTout 

Receive decoded data from the image processing subsystem. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

void DecDCTout( 

unsigned long “cell, Pointer to decoded image data 

long size) Received data size (long words) 

Explanation 


The RLE-encoded MDEC image data previously specified in a DecDCTin() call is decoded and stored in the 
buffer specified by the cell parameter. The amount of data is specified in long words by size (e.g. size=1000 
to transfer 4000 bytes of data). Multiple calls to DecDCTout() may be made to retrieve image data. 











You must specify a size value that is the same as or smaller than the available decoded data. If there is 
more data available than is read by one DecDCTout() call, additional calls must be made to avoid MDEC 
transmission deadlocks. 


The decoded image is output one 16 x 16 macroblock at a time. size must be a multiple of the total 
macroblock size for the current decoding mode. If decoding to 16-bit, a macroblock is 128 words. If 
decoding to 24-bit, the macroblock length is 192 words. 








DecDCTout() is non-blocking. To detect when execution is complete, use DecDCToutSync() or install a 
callback routine with DecDCToutCallback(). If a DecDCTout() call is executed before a previous one has 
finished, the transmission is blocked until the previous operation is complete. 





See also 
DecDCTin(), DecDCToutSync(), DecDCToutCallback() 
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DecDCToutCallback 

Install a callback routine to be called at termination of MDEC transmission. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

long DecDCToutCallback( 

long (*func)()) Pointer to callback function address 

Explanation 


Installs the user-defined callback routine specified by func. This routine is called when the data transmission 
initiated by a DecDCTout() call has been completed. If func is O, any previous callback routine is disabled. 


Although the specified function is called during an interrupt, it is not an interrupt handler; it should be 
written as a normal subroutine that is called by the main interrupt handler. Inside the callback, subsequent 
transmission termination interrupts are masked; therefore, the callback should return as soon as possible. 


Return value 
A pointer to the previously set callback function. 


See also 
DecDCTout() 
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DecDCToutSync 

Detect termination of DecDCTout(). 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

long DecDCToutSync( 

long mode) O: blocks until termination; 1: performs only status notification 

Explanation 


Detects termination of DecDCTout(). 


Return value 
Image processing subsystem status: 1 if reception is in progress and 0 if reception is not being performed. 


See also 
DecDCTout() 
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DecDCTPutEnv 

Set image-processing-subsystem environment. 
Library Header File Introduced Documentation Date 
libpress. lib lippress.h 3.5 12/14/98 

Syntax 

DECDCTENV *DecDCTPutEnv( 

DECDCTENV “env) Pointer to decoding environment 

Explanation 


Sets the quantization tables and environment data used during the reverse-quantization step of the MDEC 
decoding process. 


Return value 
Address of env. 


See also 
DecDCTGetEnv() 
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DecDCTReset 

Initialize image processing subsystem. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

void DecDCTReset( 

long mode) O: Initializes all internal states 


1: Discontinues only current decoding; does not affect internal states 


Explanation 
Resets the image processing subsystem. 





Processing time is longer for mode O than for mode 1 because internal tables are initialized. 
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DecDCTvic 

Decode Huffman-compressed MDEC image data. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 2.X 12/14/98 

Syntax 

int DecDCTvic( 

u_long “bs, Input bitstream 

u_long “buf) Output runlevel 

Explanation 


Builds the run-level intermediate format in buf by decoding the bitstream bs. If runlevel data exceeds the 
value specified in DecDCTvicSize(), DecDCTvic() is interrupted and returns control to the application. 

The interrupted VLC decode can be restarted by executing DecDCTvic (0,0). 

With buf, the 1 word area added to the header buffer in DecDCTBufSize() must be reserved in advance. 





This is a blocking function. 

This function is only the first stage of decoding an MDEC image. The Huffman-encoded bitstream must 
always be decoded using DecDCTvic() before DecDCTin() is executed. 

A partial result run level cannot be provided as DecDCTin() input. 


Return value 


0 Decoding for all bit stream is successfully 
completed. 

1 Returned with some bit stream left non- 
decoded. 

-1 Decode failed. 

See also 


DecDCTvic2(), DecDCTin(), DecDCTBufSize(), DecDCTvicSize() 
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DecDCTvic2 

Decode VLC. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.7 12/14/98 

Syntax 

int DecDCTvic2( 

u_long “bs, Input bit stream 

u_long “buf, Output run level 

DECDCTTAB table) VLC table 

Explanation 


Builds the run-level intermediate format in buf by decoding the bitstream bs using the table. When the run 
level data exceeds the value specified in DecDCTvicSize2(), DecDCTvic2() is suspended and control is 
returned to the application. The suspended VLC decoding process can be restarted by executing 
DecDCTvic2(0, O, table). With buf, the 1-word area added to the header buffer in DecDCTBufSize() must be 
reserved in advance. 








This is a blocking function. This function is only the first stage of decoding an MDEC image. The Huffman- 
encoded bitstream must always be decoded using DecDCTvic() before DecDCTin() is executed. 

A partial result run level cannot be provided as DecDCTin() input. 

The VLC table should be decoded in advance using DecDCTBuild(). 


Return value 


(0) Decoding for all bit stream is successfully 
completed. 

1 Returned with some bit stream left non- 
decoded. 

-1 Decode failed. 

See also 


DecDCTvicSize2(), DecDCTin(), DecDCTvicBuild(), DecDCTBufSize() 
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DecDCTvicBuild 


Build the VLC table. 
Library Header File Introduced Documentation Date 
libpress. lib lippress.h 3.7 12/14/98 


Syntax 

void DecDCTvlIcBuild( 

u_short “table) VLC Buffer 
Explanation 


Builds the VLC table that will be used for DecDCTvic2(). The size of the VLC table to be built can be 
obtained using sizeof (DECDCTTAB). See libpress.h for the definition of DECDCTTAB. 


The VLC table is held in a compressed (4KB) format and only when a movie is playing is it released to the 
work area and used in its decompressed form (64 KB). 


See also 
DecDCTvic2() 
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DecDCTvicSize 

Set maximum amount of data returned by a single call to DecDCTvic(). 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.2 12/14/98 

Syntax 

int DecDCTvicSize( 

int size) Maximum value of a decoded runlevel (long word) 

Explanation 


Sets the maximum number of long words that DecDCTvic() can return. Subsequent calls to DecDCTvic() 
halt after decoding size long words. If size is zero, DecDCTvic() decodes the entire bitstream regardless of 
length. 





This allows your program to make multiple calls to DecDCTvic() to decode a bitstream in chunks using a 
smaller buffer size. 


This is a blocking function. A bitstream must be converted to run-levels by DecDCTvic() before executing 
DecDCTin(). 

Return value 

Previously set buffer size. 


Example: 





/* Decoding the first VLC_SIZE word in VLC */ 
DecDCTvlcSize (VLC_SIZE); 
isvlcLeft = DecDCTvlc (next, dec.vlcbuf[dec.vlcid]); 
/* Waiting for data to be completed */ 
do { 
/* Decoding the remaining VLC_SIZE words in VLC */ 
if (isvicLeft) { 
isvlcLeft = DecDCTvlc (0, 0); 
FntPrint ("%d, ", VSync (1)); 








} 

/* Application code is here */ 
} while (isvlcLeft || isEndOfFlame == 0); 
isEndOfFlame = 0; 








See also 
DecDCTvic(), DecDCTin() 
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DecDCTvicSize2 

Set maximum size of single VLC decoding process. 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 3.7 12/14/98 

Syntax 

int DecDCTvicSize2( 

int size) Maximum value of a decoded runlevel (long word) 

Explanation 


Sets the maximum size of bitstream that can be decoded per decoding process. DecDCTvic2() suspends 
the decoding process when decoding the first block after the number of words specified by size. If size is O 
(the default), the decoding process is not suspended. 


Since this is a blocking function, the bit stream must be converted to a run level by DecDCTvic2() before 
executing DecDCTin(). 


Return value 
Maximum run level set immediate before. 





See also 
DecDCTvic2(), DecDCTin() 
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EncSPU 

Encode 16-bit PCM data into PlayStation waveform format. 
Library Header File Introduced Documentation Date 
libpress.lib libpress.h 3.6 12/14/98 

Syntax 

long EncSPU( 

ENCSPUENV “es_env) SPU encode environment attribute structure 

Explanation 


Encodes the 16-bit straight PCM data specified by es_env.src into PlayStation waveform data (VAG, 
without header information) and returns the encoded data in es_env.dest. 





16-bit straight PCM data size in es_env.size is specified in byte units. When creating looping waveforms, 
specify es_env.loop as ENCSPU_ENCODE_LOOP and specify es_env./oop_start as the es_env.src internal 
PCM data loop start point in byte units. 





If es_env.loop_start is not a multiple of 56 (28 samples), the loop start point is set to the next lower multiple 
of 56. If it is not looping waveform, specify es_env.loop as ENCSPU_ENCODE_NO_LOOP. 


To ensure proper compression of different PCM endian formats, specify es_env.byte_swap as 
ENCSPU_ENCODE_ENDIAN_BIG (16-bit big endian) or ENCSPU_ENCODE_ENDIAN_LITTLE (16-bit little 
endian). 


Whole/Divided encoding specifications are performed by specifying an attribute to es_env.proceed: 











es_env.proceed Encoding Specifications 
ENCSPU_ENCODE_WHOLE Whole encoding 
ENCSPU_ENCODE_START Start divided encoding 





ENCSPU_ENCODE_CONTINUE Continue divided encoding 














ENCSPU_ENCODE_END End divided encoding 





When es_env.proceed is set to something other than ENCSPU_ENCODE_WHOLE, the area is divided, in 
other words, the following encoding is performed only in the area specified from es_env.src to es_env.size: 
e Encoding by ENCSPU_ENCODE_START of the area including the start block 

e Continued encoding by ENCSPU_ENCODE_CONTINUE of the intermediate area 

e Encoding by ENCSPU_ENCODE_END of the section including the end block 





If es_env.size is not a multiple of 56 (28 samples), the data is padded with zeroes until it is. This could 
cause the generated waveform to be discontinuous; to maintain continuity, perform a divided encode on 
the data with es_env.size equal to a multiple of 56. 





If es_env.proceed is set to ENCSPU_ENCODE_WHOLE, the waveform is padded with zeroes to make 
es_env.size a multiple of 56, and waveform encoding is performed all at once. 


To use the scratchpad as the workspace, specify es_env.work as the scratchpad address; use 168 bytes 
from the specified address. If es_env.work is set to NULL, the automatic variables are used internally. 


When loop is specified as ENCSPU_ENCODE_NO_LOOP, /oop_start will be ignored. 
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Return value 
The data size of the encoded waveform (VAG). 


ENC_ENCODE_ERROR is returned when an encoding error occurs. 











Notes 
Be aware that processing speed is faster with EncSPu than EncSPU2, but sound quality is poorer. 
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EncSPU2 

Encode 16-bit PCM data into PlayStation waveform format (EncSPU2 high quality sound version) 
Library Header File Introduced Documentation Date 
libpress. lib libpress.h 4.6 8/27/99 

Syntax 


long EncSPU2( 
ENCSPUENV “es_env) SPU encode environment attribute structure 
Explanation 


Encodes the 16-bit straight PCM data specified by es_env.src into PlayStation waveform data (VAG, 
without header information) and returns the encoded data in es_env.dest. 





16-bit straight PCM data size in es_env.size is specified in byte units. When creating looping waveforms, 
specify es_env.loop as ENCSPU_ENCODE_LOOP and specify es_env./oop_start as the es_env.src internal 
PCM data loop start point in byte units. 


If es_env.loop_start is not a multiple of 56 (28 samples), the loop start point is set to the next lower multiple 
of 56. If it is not looping waveform, specify es_env.loop as ENCSPU_ENCODE_NO_LOOP. 





To ensure proper compression of different PCM endian formats, specify es_env.byte_swap as 
ENCSPU_ENCODE_ENDIAN_BIG (16-bit big endian) or ENCSPU_ENCODE_ENDIAN_LITTLE (16-bit little 
endian). 


Whole/Divided encoding specifications are performed by specifiying an attribute to es_env.proceed: 











es_env.proceed Encoding Specifications 
ENCSPU_ENCODE_WHOLE Whole encoding 
ENCSPU_ENCODE_START Start divided encoding 





ENCSPU_ENCODE_CONTINUE Continue divided encoding 














ENCSPU_ENCODE_END End divided encoding 





When es_env.proceed is set to something other than ENCSPU_ENCODE_WHOLE, the area is divided, in 
other words, the following encoding is performed only in the area specified from es_env.src to es_env.size: 
e Encoding by ENCSPU_ENCODE_START of the area including the start block 

e Continued encoding by ENCSPU_ENCODE_CONTINUE of the intermediate area 

e Encoding by ENCSPU_ENCODE_END of the section including the end block 





If es_env.size is not a multiple of 56 (28 samples), the data is padded with zeroes until it is. This could 
cause the generated waveform to be discontinuous; to maintain continuity, perform a divided encode on 
the data with es_env.size equal to a multiple of 56. 





If es_env.proceed is set to ENCSPU_ENCODE_WHOLE, the waveform is padded with zeroes to make 
es_env.size a multiple of 56, and waveform encoding is performed all at once. 


To use the scratchpad as the workspace, specify es_env.work as the scratchpad address; use 168 bytes 
from the specified address. If es_env.work is set to NULL, the automatic variables are used internally. 


However, when es_env_quality is set to ENCSPU_ENCODE_HIGH_QUALITY, only NULL can be specified. 
With regard to quality and speed, when es_env_quality is set to ENCSPU_ENCODE_MIDDLE_QUALITY, 
encoding is performed with an emphasis on speed rather than quality. When es_env_quality is set to 
ENCSPU_ENCODE_HIGH_QUALITY, though, the emphasis is placed on quality rather than speed. 
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When /oop is specified as ENCSPU_ENCODE_NO_LOOP, /oop_start will be ignored. 


Return value 
The data size of the encoded waveform (VAG). 





ENC_ENCODE_ERROR is returned when an encoding error occurs. 








Notes 
Be aware that sound quality is better with EncSPU2 than EncSPU, but processing is slower. 


CONFIDENTIAL Run-Time Library Reference 


Chapter 7: Basic Graphics Library 
Table of Contents 











Structures 
DISPENV 7-5 
DRAWENV 7-6 
DR_AREA 7-7 
DR_ENV 7-8 
DR_LOAD 7-9 
DR_MODE 7-10 
DR_MOVE 7-11 
DR_OFFSET 7-12 
DR_STP 7-13 
DR_TPAGE 7-14 
DR_TWIN 7-15 
LINE_F2, LINE_F3, LINE_F4 7-16 
LINE_G2, LINE_G3, LINE_G4 7-17 
POLY_F8, POLY_F4 7-19 
POLY_FT8, POLY_FT4 7-20 
POLY_G3, POLY_G4 7-22 
POLY_GT8, POLY_GT4 7-23 
RECT 7-25 
RECT32 7-26 
SPRT 7-27 
SPRT_8, SPRT_16 7-28 
TILE 7-29 
TILE_1, TILE_8, TILE_16 7-30 
TIM_IMAGE 7-31 
TMD_PRIM 7-32 
Functions 
AddPrim, addPrim 7-33 
AddPrims, addPrims 7-34 
BreakDraw 7-35 
CatPrim, catPrim 7-36 
CheckPrim 7-37 
Clearlmage 7-38 
Clearlmage2 7-39 
ClearOTag 7-40 
ClearOTagR 7-41 
ContinueDraw 7-42 
DrawOTag 7-43 
DrawOTag2 7-44 
DrawOTagEnv 7-45 
DrawOTaglO 7-46 
DrawPrim 7-47 
DrawSync 7-48 
DrawSyncCallback 7-49 
DumpClut, dumpClut 7-50 
DumpDispEnv 7-51 
DumpDrawEnv 7-52 
DumpOTag 7-53 


Run-Time Library Reference 


DumpTPage, dumpTPage 
FntFlush 

FntLoad 

FntOpen 

FntPrint 

GetClut, getClut 
GetDispEnv 
GetDrawArea 
GetDrawEnv 
GetDrawEnv2 
GetDrawMode 
GetDrawOffset 
GetGraphDebug 
GetODE 
GetTexWindow 
GetTimSize 
GetTPage, getTPage 
IsEndPrim, isendprim 
IsldleGPU 
KanjiFntClose 
KanjiFntFlush 
KanjiFntOpen 
KanjiFntPrint 
Krom2Tim 
LoadClut 
LoadClut2 
Loadimage 
Loadlmage2 
LoadTPage 
MargePrim 
Movelmage 
Movelmage2 
NextPrim, nextPrim 
OpenTIM 
OpenTMD 
PutDispEnv 
PutDrawEnv 
ReadT|IM 
ReadTMD 
ResetGraph 
SetDefDispEnv 
SetDefDrawEnv 
SetDispMask 
SetDrawArea 
SetDrawEnv 
SetDrawLoad 
SetDrawMode, setDrawMode 
SetDrawMove 
SetDrawOffset 
SetDrawStpo 
SetDrawTPage, setDrawTPage 
SetDumpFnt 
SetGraphDebug 
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7-54 
7-55 
7-56 
7-57 
7-58 
7-59 
7-60 
7-61 
7-62 
7-63 
7-64 
7-65 
7-66 
7-67 
7-68 
7-69 
7-70 
7-74 
1-72 
1-13 
7-74 
1-15 
7-76 
7-77 
7-78 
7-79 
7-80 
7-81 
7-82 
7-83 
7-84 
7-85 
7-86 
7-87 
7-88 
7-89 
7-90 
7-91 
7-92 
7-93 
7-94 
7-95 
7-96 
7-97 
7-98 
7-99 
7-100 
7-101 
7-102 
7-103 
7-104 
7-105 
7-106 








SetLineF2, SetLineF3, SetLineF4; setLineF2, setLineF3, setLineF4; SetLineG2, SetLineGs, 




















SetLineG4; setLineG2, setLineG3, setLineG4 7-107 
SetPolyF3, SetPolyF4; setPolyF3, setPolyF4; SetPolyG3, SetPolyG4; setPolyG3, setPolyG4; 

SetPolyGT3, SetPolyGT4; setPolyGT3, setPolyGT4 7-108 
SetSemiTrans, setSemiTrans 7-109 
SetShadeTex, setShadeTex 7-110 
SetSprt, SetSprt8, SetSprt16; setSprt, setSprt8, setSprt16 7-111 
SetTexWindow 7-112 
SetTile, SetTile1, SetTile8, SetTile16; setTile, setTile1, setTile8, setTile16 7-113 
Storelmage 7-114 
Storelmage2 7-115 
TermPrim, termPrim 7-116 
VSync 7-117 
VSyncCallback 7-118 

Macros 

addVector 7-119 
applyVector 7-120 
copyVector 7-121 
dumpMatrix 7-122 
dumpRECT 7-123 
dumpVector 7-124 
dump... 7-125 
setClut 7-126 
setRECT 7-127 
setRGBO, setRGB1, setRGB2, setRGB3 7-128 
setTPage 7-129 
setUVO, setUV3, setUV4 7-130 
setUVWH 7-131 
setVector 7-132 
setWH 7-133 
setXYO, setXY2, setXY3, setXY4 7-134 
setXYWH 7-135 
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Structures 
DISPENV 
Display environment. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct DISPENV { 
RECT disp; Display area within frame buffer. Width: 256, 320, 384, 512, or 640. Height: 
240 or 480. 
RECT screen; Output screen display area. It is calculated without regard to the value of 


disp, using the standard monitor screen upper left-hand point (0, 0) and 
lower right-hand point (256, 240). 





u_char isinter; Interlace mode flag. 0: non-interlace; 1: interlace 
u_char isrgb24; 24-bit mode flag. 0: 16-bit mode; 1: 24-bit mode 
u_char pad0, pad7; Reserved by system 

} 

Explanation 


Specifies display parameters for screen display mode, frame buffer display value, and so on. 


See also 
DumpDispEnv(), GetDispEnv(), PutDispEnv(), SetDefDispEnv() 
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DRAWENV 
Drawing environment. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct DRAWENV { 
RECT clip; Drawing area. Drawing is restricted to the area specified by clip. It must be 
within the area area (O, 0) - (1023, 511). 
short ofs/2]; The offsets ofs/O] and ofs[1] are added to the X and Y values, respectively, of 


all primitives before drawing. Note: Addresses after adding offsets are 
wrapped around at (-1024, -1024) - (1023, 1023). 








RECT tw; Texture window. Specifies a rectangle inside the texture page, to be used 
for drawing textures. 

u_short tpage; Initial value of texture page 

u_char dtd; Dithering processing flag. O: off; 1: on 

u_char dfe; O: drawing to display area is blocked 
1: drawing to display area is permitted 

u_char isbg; 0: Does not clear drawing area when drawing environment is set. 


1: Paints entire clio area with brightness values (r0, gO, bO) when drawing 
environment is set. 


u_char r0, gO, bO; Background color. Valid only when isbg is 1. 
DR_ENV dr_env; System reserved 

i 

Explanation 


Sets basic drawing parameters, such as drawing offset and drawing clip area. 


The GPU uses 8 bits for R, G, B internally; when writing to the frame buffer, each value is reduced to 5 bits. 
When dtd is ON, a 4x4 dither matrix is used as follows: 


i = 8 bit brightness value + 1/2 * D- 4 
D = Dither matrix [X%4] [Y%4] 


Table 7-1: 4x4 Dither Matrix 





O 8 2 10 
12 4 14 6 
3 11 1 9 
15 1 13 5 





5 bit brightness value = 1 >> 3 


The values which may be specified for the texture window are restricted to the following combinations: 

















Table 7-2 
tw.w, tw.x 
tw.w O (=256) 8 16 32 64 128 
tw.x O Multiple of | Multiple of Multiple of Multiple of Multiple of 
8 16 32 64 128 
tw.h, tw.y 
tw.h O (=256) 8 16 32 64 128 
tw.y O Multiple of Multiple of Multiple of Multiple of Multiple of 
8 16 32 64 128 
See also 


DrawOTagEnv(), DumpDrawEnv(), GetDrawEnv(), PutDrawEnv(), SetDefDrawEnv(), SetDrawEnv() 


Run-Time Library Reference 


Basic Graphics Library Structures 7-7 


DR_AREA 


Drawing area change primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 


Structure 
struct DR_AREA { 
u_long “tag; Pointer to the next primitive in primitive list 
u_long code/2]; New drawing area information specified by SetDrawArea() 
} 
Explanation 


Modifies the drawing area of the current drawing environment while a primitive list is being drawn. Use 
SetDrawArea() to set the contents of this primitive. 


See also 
GetDrawArea(), SetDrawArea() 
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DR_ENV 


Drawing environment modification primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Structure 
struct DR_ENV { 
u_long “tag; Pointer to the next primitive in primitive list 
u_long code/75]; New drawing environment information specified by SetDrawEnv() 
} 
Explanation 


Changes the drawing environment (DRAWENV) while a primitive list is being drawn. Use SetDrawEnv() to 
specify the new DRAWENV parameters. 


This primitive affects only the drawing environment, not the display environment (see DISPENV). The entire 
drawing environment may be changed using this primitive; see also the DR_MODE primitive, which sets a 
subset of the drawing environment. 


See also 
SetDrawEnv(), PutDrawEnv() 
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DR_LOAD 


Load Image primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.4 12/14/98 


Structure 

typedef struct { 
u_long “tag; Pointer to next primitive (reserved) 
u_long code/[3]; Primitive ID 
u_long p/73]; Transfer data 

} DR_LOAD; 


Explanation 


Transfers data below array p to the frame buffer. As with Loadimage(), semitransparent/ transparent color 
control is not performed. Also, there is no dependence on the drawing environment. 





Maximum data transfer amount is 12 words (24 pixels). 


See also 
Loadimage(), SetDrawLoad() 
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DR_MODE 
Drawing mode modification primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.0 12/14/98 
Structure 
typedef struct { 
u_long “tag; Pointer to the next primitive in primitive list 
u_long code/2]; New drawing environment information as specified by 
SetDrawMode() 
} DR_MODE; 
Explanation 


Changes the texture page, texture window, dithering flag, and drawing flag parameters of the current 
drawing environment while a primitive list is being drawn. See the tpage, tw, dtd, and dfe members of the 
DRAWENYV structure for more information. Use SetDrawMode() to specify the parameters to be used. 








See also 
SetDrawMode(), GetDrawMode() 
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DR_MOVE 


Rectangle copy primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.2 12/14/98 


Structure 

typedef struct { 
u_long tag; Hook to the next primitive (reserved) 
u_long code/5]; Primitive ID 

} DR_MOVE; 

Explanation 

Copies a rectangle. Speed is the same as Movelmage(). 


Unlike the 16-bit SPRT primitive, semitransparent/transparent color control is not carried out. Also, transfer 
does not depend on the drawing environment. 


See also 
Movelmage(), Movelmage2(), SetDrawMove() 
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DR_OFFSET 


Drawing offset modification primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 


Structure 


typedef struct { 

u_long “tag; Pointer to the next primitive in primitive list 

u_long code/2]; New drawing offset information specified by SetDrawOffset() 
} DR_OFFSET; 


Explanation 


Changes the drawing offset parameters of the current drawing environment while a primitive list is being 
drawn. See the ofs member of the DRAWENV structure for more information. Use SetDrawOffset() to 
specify the parameters to be used. 


See also 
GetDrawOffset(), SetDrawOffset() 
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DR_STP 
STP bit updated primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.1 12/14/98 


Structure 
typedef struct DR_STP { 
u_long tag; Pointer to the next primitive in primitive list (reserved) 
u_long code/2]; Primitive ID 
} DR_STP; 
Explanation 
Updates the STP bit during drawing. Use SetDrawStp() to set the contents of this primitive. 


See also 
SetDrawStp() 
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DR_TPAGE 
Texture page change primitive. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 35 12/14/98 
Structure 
typedef struct { 
u_long “tag; Pointer to the next primitive in primitive list 
u_long code/2]; New texture page information specified by SetDrawTPage() 
} DR_TPAGE; 
Explanation 


Changes the texture page parameter of the current drawing environment while a primitive list is being 
drawn. See the toage member of the DRAWENYV structure for more information. Use SetDrawTPage() to 
specify the parameters to be used. 


See also 
SetDrawTPage() 
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DR_TWIN 
Texture window change primitives. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.0 12/14/98 
Structure 
typedef struct { 
u_long “tag; Pointer to the next primitive in primitive list 
u_long code/2]; New texture window information specified by 
SetDrawTexWindow() 
} DR_TWIN; 
Explanation 


Changes the texture window of the current drawing environment while a primitive list is being drawn. See 
the tw member of the DRAWENV structure for more information. Use SetTexWindow() to specify the 
parameters to be used. 





See also 
GetTexWindow(), SetTexWindow() 
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LINE_F2, LINE_F3, LINE_F4 


One flat-shaded non-connecting line/ Two flat-shaded connected lines/ Three flat-shaded connected lines. 





Library Introduced Documentation Date 
libgpu. lib 2.X 12/14/98 
Structure 
struct LINE_F2 { 
u_long “tag; Pointer to the next primitive (reserved) 
u_char r0, gO, bO; RGB color specifed by straight line 
u_char code; Primitive ID 


short xO, yO, x7, y1; 
} 


struct LINE_F3 { 


Coordinate of vertices forming straight lines 


u_long *tag; Pointer to the next primitive (reserved) 
u_char r0, gO, bO; RGB color specifed by straight line 

u_char code; Primitive ID 

short xO, yO, x1, y1, x2, y2; Coordinate of vertices forming straight lines 
u_long pad; Reserved 


struct LINE_F4 { 


u_long “tag; Pointer to the next primitive (reserved) 
u_char r0, gO, bO; RGB color specifed by straight line 
u_char code; Primitive ID 
short xO, yO, x7, y1, x2, y2, X3, Coordinate of vertices forming straight lines 
y3; 
u_long pad; Reserved 
Explanation 


LINE_F2 draws a non-connecting line linking (xO, yO) - (x7, y1) with the RGB color specifed by (rO, g0, bO). 


LINE_F3 draws 2 connecting lines linking (xO, yO) - (x7, y1) - (x2, y2) with the RGB color specifed by (rO, 90, 


bO). 


LINE_F4 draws 3 connecting lines linking (xO, yO) - (x1, y1) - (x2, y2) - (x3, y3), with the RGB color specifed 


by (rO, gO, bO). 


See also 
SetLineF2() 


Run-Time Library Reference 





Basic Graphics Library Structures 7-17 


LINE_G2, LINE_G3, LINE_G4 
One Gouraud-shaded non-connecting line/ Two Gouraud-shaded connected lines/ Three Gouraud-shaded 
connected lines 





Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.x 12/14/98 
Structure 
struct LINE_G2 { 
u_long “tag; Pointer to the next primitive 


u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char r1, g1, b1; RGB color values 
u_char p1; Primitive ID (reserved) 
short x1, y1; Vertex coordinates 


} 


struct LINE_G3 { 


u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char r1, g1, b1; RGB color values 
u_char p1; Primitive ID (reserved) 
short x1, y1; Vertex coordinates 
u_char r2, 92, b2; RGB color values 
u_char p2; Primitive ID (reserved) 
short x2, y2; Vertex coordinates 
u_long pad; Reserved 


struct LINE_G4 { 


u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char r1, g1, 67; RGB color values 
u_char p1; Primitive ID (reserved) 
short x1, y1; Vertex coordinates 
u_char r2, 92, b2; RGB color values 
u_char p2; Primitive ID (reserved) 
short x2, y2; Vertex coordinates 
u_char r3, g3, b3; RGB color values 
u_char p3; Primitive ID (reserved) 
short x3, y3; Vertex coordinates 
u_long pad; Reserved 
Explanation 


LINE_G2 draws a non-connecting line linking (xO, yO) - (x1, y1) in such a way that its vertices have the RGB 
color specified by (rO, gO, bO) - (r1, g1, b1), and perform Gouraud shading at the same time. 


LINE_G3 draws connecting lines linking (xO, yO) - (x7, y1)- (x2, y2) in such a way that their vertices have the 
RGB color specified by (rO, gO, bO) - (r1, g1, b1) - (r2, g2, b2), and perform Gouraud shading at the same 
time. 
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LINE_G4 draws connecting lines linking (xO, yO) - (x1, y7)- (x2, y2) - (x3, y3) in such a way that their vertices 
have the RGB color specified by (rO, gO, bO) - (r1, g1, b1) - (r2, g2, b2) - (r3, g3, b3) and perform Gouraud 
shading at the same time. 


See also 
SetLineF2() 
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POLY_F3, POLY_F4 


Flat-shaded, non-textured mapped triangel/ Flat-shaded, not-textured mapped quad. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Structure 

struct POLY _F3{ 
u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
short x7, y1; Vertex coordinates 
short x2, y2; Vertex coordinates 

} 

struct POLY_F4 { 
u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, y0; Vertex coordinates 
short x7, y1; Vertex coordinates 
short x2, y2; Vertex coordinates 
short x3, y3; Vertex coordinates 

} 

Explanation 


POLY_F3 paints the area demarcated by (x0, y0) - (x1, y1) - (x2, y2) using RGB color specified by (ro, gO, 
bo). 

POLY_F4 paints the area demarcated by (xO, yO) - (x1, y1) - (x3, y3) - (x2, y2) using RGB color specified by 
(ro, g0, bO). 


The address where a picture is actually drawn is equivalent to the value of xO-x3 to which the offset value 
specified by the drawing environment is added. What is drawn is clipped according to the clip area 
(quadrilateral area) specified by the drawing environment. 











If the polygon has a width greater than 1024 and a height greater than 512, all of it is clipped. In the case of 
a quadrilateral primitive, the corners are specified in the order shown below. 


Figure 7-1 
(x0, yO) (x1,y1) 
(x2, y2) (x3, y3) 
See also 
SetPolyF30 
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POLY_FT3, POLY_FT4 


Flat-shaded, texture-mapped triangle/ Flat-shaded, texture-mapped quad. 





Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 
Structure 
struct POLY_FTS { 
u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char u0, vO; Texture coordinates 
u_short clut; CLUT ID (color-look-up table for 4-bit/8-bit mode only) 
short x7, y7; Vertex coordinates 


u_char u7, v7; 
u_short tpage; 


Texture coordinates 
Texture page ID 


short x2, y2; Vertex coordinates 
u_char u2, v2; Texture coordinates 
u_short pad7; Reserved by the system 


} 


struct POLY_FT4 { 





u_long “tag; Pointer to the next primitive 

u_char r0, gO, bO; RGB color values 

u_char code; Primitive ID (reserved) 

short xO, yO; Vertex coordinates 

u_char u0, vO; Texture coordinates 

u_short clut; CLUT ID (color-look-up table for 4-bit/8-bit mode only) 
short x7, y7; Vertex coordinates 


u_char u7, v7; 
u_short tpage; 


Texture coordinates 
Texture page ID 


short x2, y2; Vertex coordinates 
u_char u2, v2; Texture coordinates 
u_short pad7; Reserved by the system 
short x3, y3; Vertex coordinates 
u_char u3, v3; Texture coordinates 
u_short pad2; Reserved by the system 

} 

Explanation 


POLY_FTS8 draws an area demarcated by (x0, yO) - (x7, y1) - (x2, y2) while mapping the area demarcated 
by (uO, vO) - (u1, v7) - (U2, v2) in the texture pattern on the texture page toage. 


POLY_FT4 draws an area demarcated by (xO, yO) - (x7, y1) - (x3, y3) - (x2, y2) while mapping the area 
demarcated by (u0, vO) - (u1, v7) - (u3, v3) - (U2, v2) in the texture pattern on the texture page tpage. 


The actual brightness value for drawn graphics are obtained by multiplying the RGB color values from the 
texture pattern by the RGB color values given by rO, gO, bO. 








The texture coordinates are the coordinates (0 to 255) inside the texture page corresponding to the vertices 
of the triangle to be drawn. if the texture mode is 4-bit or 8-bit, the texture coordinates and the actual frame 
buffer address are not 1-to-1. 





Texture page ID is given to toage. Using GetTPage(), the texture page ID is obtained from the address (x, y) 
of the buffer frame where the texture page is located. 


A texture using CLUT gives CLUT ID to be set in clut. Using GetClut(), CLUT ID is obtained from the 
address (x, y) of the frame buffer where CLUT is located. 
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The size of the texture page which can be used by one drawing command is 256 x 256. One primitive can 
only use one texture page. 








In the case of a quadrilateral primitive, the corners are specified in the order shown below. The same 
applies to designation of (u, v) for a texture map rectangle, and (r, g, b) for a Gouraud shaded rectangle. 





Figure 7-2 
(xO, yO) (x1,y1) 


(x2, y2) (x3, y3) 


See also 
GetTPage(), GetClut(), SetPolyF3() 
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POLY_G3, POLY _G4 


Gouraud-shaded, non-textured mapped triangle/ Gouraud-shaded, non-textured mapped quad. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Structure 

struct POLY_G3 { 
u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char r1, g1, 67; RGB color values 
u_char pad1; Reserved by the system 
short x1, y1; Vertex coordinates 
u_char r2, 92, b2; RGB color values 
u_char pad2; Reserved by the system 
short x2, y2; Vertex coordinates 

} 

struct POLY_G4 { 
u_long “tag; Pointer to the next primitive 
u_char r0, gO, bO; RGB color values 
u_char code; Primitive ID (reserved) 
short xO, yO; Vertex coordinates 
u_char r1, g1, b1; RGB color values 
u_char pad1; Reserved by the system 
short x1, y1; Vertex coordinates 
u_char r2, 92, b2; RGB color values 
u_char pad2; Reserved by the system 
short x2, y2; Vertex coordinates 
u_char r3, g3, b3; RGB color values 
u_char pad3; Reserved by the system 
short x3, y3; Vertex coordinates 

} 

Explanation 


When drawing while performing Gouraud shading, POLY_G3 paints the area demarcated by (xO, yO) - (x7, 
y1) - (x2, y2) so that vertex RGB color value may be set to (rO, gO, bO) - (r1, g1, b1) - (r2, g2, b2). 


When drawing while performing Gouraud shading, POLY_G4 paints the area demarcated by (xO, yO) - (x7, 
y1) - (x8, y3) - (x2, y2) so that vertex RGB color value may be set to (rO, gO, bO) - (r1, g1, b1) - (r3, g3, b3) - 
(r2, 92, b2). 


The brightness of triangle-internal pixels is calculated by performing linear interpolation of the RGB color 
values of the three vertices. (Gouraud shading). 








See also 
SetPolyF30 


Run-Time Library Reference 





POLY_GT3, POLY_GT4 


Gouraud-shaded, texture-mapped triangle/ Gouraud-shaded, texture-mapped quad. 


Library 
libgpu. lib 


Structure 
struct POLY_GTS3 { 


u_long “tag; 


u_char r0, gO, bO; 


u_char code; 
short xO, yO; 
u_char u0, vO; 
u_short clut; 


u_char r7, g1, b1; 


u_char p1; 
short x7, y7; 
u_char u1, v7; 
u_short tpage; 


u_char r2, 92, b2; 


u_char p2; 
short x2, y2; 
u_char u2, v2; 
u_short pad2; 


struct POLY_GT4 { 


} 


u_long “tag; 


u_char r0, gO, bO; 


u_char code; 
short xO, yO; 
u_char u0, vO; 
u_short clut; 


u_char r7, g1, b1; 


u_char p1; 
short x7, y7; 
u_char u7, v7; 
u_short tpage; 


u_char r2, 92, b2; 


u_char p2; 
short x2, y2; 
u_char u2, v2; 
u_short pad2; 


u_char r3, g3, b3; 


u_char p3; 
short x3, y3; 
u_char u3, v3; 
u_short pad3; 


Explanation 
POLY_GT3 draws a triangle performing texture mapping and Gouraud shading simultaneously. 


Header File 
libgpu.h 2.X 


Documentation Date 
12/14/98 


Introduced 


Pointer to the next primitive 
RGB color values 

Primitive ID (reserved) 
Vertex coordinates 

Texture coordinates 

CLUT ID (color-look-up table for 4-bit/8-bit mode only) 
RGB color values 

Reserved 

Vertex coordinates 

Texture coordinates 
Texture page ID 

RGB color values 

Reserved 

Vertex coordinates 

Texture coordinates 
Reserved by the system 


Pointer to the next primitive 
RGB color values 
Primitive ID (reserved) 
Vertex coordinates 
Texture coordinates 
CLUT ID (color-look-up table for 4-bit/8-bit mode only) 
RGB color values 
Primitive ID (reserved) 
Vertex coordinates 
Texture coordinates 
Texture page ID 

RGB color values 
Primitive ID (reserved) 
Vertex coordinates 
Texture coordinates 
Reserved by the system 
RGB color values 
Primitive ID (reserved) 
Vertex coordinates 
Texture coordinates 
Reserved by the system 


POLY_GT4 draws a quadrilateral performing texture mapping and Gouraud shading simultaneously. 


The actual RGB color values for the picture are equal to the RGB color values obtained from the texture 
pattern multiplied by the RGB color values calculated by Gouraud shading. 
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See also 
SetPolyF8\() 
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RECT 
Frame buffer rectangular area. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct RECT { 
short x, y; Top left coordinates of the rectangular area 
short w, h; Width and height of the rectangular area 
} 
Explanation 





Used by several library functions to specify a rectangular area of the frame buffer. Neither negative values, 
nor values exceeding the size of the frame buffer (1024x512), may be specified. 


See also 
Clearlmage(), Loadimage(), Movelmage(), Storelmage(), dumpRECT(), setRECT() 
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RECT32 


Rectangular area (32 bit) 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 4.3 12/14/98 


Structure 


typedef struct { 
int x, y; Top left coordinates of the rectangular area 
int w, h; Width and height of the rectangular area 

} RECT32; 


Explanation 


Used by several library functions to specify a rectangular area of the frame buffer. Neither negative values, 
nor values exceeding the size of the frame buffer (1024x512) may be specified. 
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SPRT 
Sprite of any desired size. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct SPRT { 
u_long “tag; Pointer to next primitive (reserved) 
u_char r0, gO, bO; RGB color values for sprite 
u_char code; Primitive code (reserved) 
short xO, yO; Position of sprite (top left coordinate) 
u_char u0, vO; Position of sprite texture within the texture page (top left coordinate). uO 
should be an even number. 
u_short clut; CLUT ID used (for 4-bit/8-bit mode only) 
short w, h; Width and height of sprite. w is an even number 
} 
Explanation 


Draws a texture-mapped rectangular area. Drawing speed for a SPRT primitive is faster than for a 
POLY_FT4. 


Only even numbers can be specified for uO and w. 


Because the SPRT primitive has no tpage parameter, the texture page of the current drawing environment 
is used. You can change the texture page by inserting a DR_TPAGE or DR_MODE primitive into the 
primitive list before your SPRT primitive. 








See also 
SetSprt() 
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SPRT_8, SPRT_16 


8 x 8 fixed size, texture-mapped sprite / 16 x 16 fixed size, texture-mapped sprite. 








Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct SPRT_16 { 
u_long “tag; Pointer to next primitive (reserved) 
u_char r0, gO, bO; RGB color values for sprite 
u_char code; Primitive code (reserved) 
short xO, yO; Position of sprite (top left coordinate) 
u_char uO, vO; Position of sprite texture within the texture page (top left coordinate). uO 
should be an even number. 
u_short clut; CLUT ID used (for 4-bit/8-bit mode only) 
} 
struct SPRT_8 { 
u_long “tag; Pointer to next primitive (reserved) 
u_char r0, gO, bO; RGB color values for sprite 
u_char code; Primitive code (reserved) 
short xO, yO; Position of sprite (top left coordinate) 
u_char u0, vO; Position of sprite texture within the texture page (top left coordinate). uO 
should be an even number. 
u_short clut; CLUT ID used (for 4-bit/8-bit mode only) 
} 
Explanation 


Draws a sprite with a fixed size of 8 x 8 or 16 x 16. The same result can be obtained if 8 and 16 are 
designated as the w and h members of the SPRT structure. 


See also 
SetSpri() 
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TILE 
Tile of any desired size. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Structure 
struct TILE { 
u_long “tag; Pointer to next primitive (reserved) 
u_char r0, gO, bO; RGB color values for sprite 
u_char code; Primitive code (reserved) 
short xO, yO; Position of sprite (top left coordinate) 
short w, h; Width and height of sprite. w is an even number 
} 
Explanation 


Draws a rectangular area with the specified RGB color value (rO, gO, bO). No texture mapping or shading is 
done. It is faster than the POLY_F4 primitive. 


See also 
SetTile() 
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TILE_1, TILE_8, TILE_16 


1 x 1 fixed-size tile sprite / 8 x 8 fixed-size tile sprite / 16 x 16 fixed-size tile sprite. 


Library 
libgpu.lib 


Structure 

struct TILE_16 { 
u_long “tag; 
u_char r0, gO, bO; 
u_char code; 
short xO, y0; 

} 


struct TILE_8 { 
u_long “tag; 
u_char r0, gO, bO; 
u_char code; 
short xO, yO; 

} 


struct TILE_1 { 


u_long “tag; 
u_char r0, gO, bO; 
u_char code; 
short xO, y0; 

} 

Explanation 


Header File 
libgpu.h 


Documentation Date 
12/14/98 


Introduced 
2.X 


Pointer to next primitive (reserved) 
RGB color values for sprite 

Primitive code (reserved) 

Position of sprite (top left coordinate) 


Pointer to next primitive (reserved) 
RGB color values for sprite 

Primitive code (reserved) 

Position of sprite (top left coordinate) 


Pointer to next primitive (reserved) 
RGB color values for sprite 

Primitive code (reserved) 

Position of sprite (top left coordinate) 


Fixed-size versions of the TILE primitive. The rectangular area is drawn with the specified RGB color value 
(rO, gO, bO). No texture mapping or shading is done. These are faster than the POLY_F4 primitive. 


See also 
SetTile() 
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TIM_IMAGE 
TIM format image data header. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 
Structure 
typedef struct { 
u_long mode; Pixel mode 
RECT *crect; Pointer to destination rectangle in VRAM for CLUT data 
u_long *caddr; Pointer to address of CLUT data in main memory 
RECT *prect; Pointer to destination rectangle in VRAM for texture image data 
u_long “pada; Pointer to address of texture image data in main memory 
} TIM_IMAGE; 
Explanation 


TIM data header information is acquired by ReadTIM(). 


crect and cadadr are assigned a value of zero for TIM having no CLUT. 


See also 
ReadT|IM() 
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TMD_PRIM 


TMD format model data header. 


Library Header File Introduced 
libgpu. lib libgpu.h 2.X 
Structure 
typedef struct { 
u_long id; TMD primitive ID 


u_char r0, gO, bO, pO; 
u_char r7, g1, b1, p1; 
u_char r2, 92, b2, p2; 
u_char r3, g3, b3, p3; 
u_short tpage; 
u_short clut; 
u_char uO, vO, u1, v7; 
u_char u2, v2, u3, v3; 
SVECTOR xO, x1, x2, x3; 
SVECTOR nO, n1, n2, n3; 
SVECTOR *v_ofs; 
SVECTOR *n_ofs; 
u_short verto, vert7; 
u_short vert2, vert3; 
u_short norm0, norm7; 
u_short norm2, norm3; 

} TMD_PRIM; 


Explanation 


Information on primitives constituting a TMD object. The information is acquired using ReadTMD)(). xO, x7, 
X3, n0, n1,n3 are used for an independent vertex model. v_ofs, n_ofs and vertO,..vert3, normO...norm3 are 


used for a common vertex model. 


RGB color values of vertex 1 (+ 1-byte pad) 
RGB color values of vertex 2 (+ 1-byte pad) 
RGB color values of vertex 3 (+ 1-byte pad) 
RGB color values of vertex 4 (+ 1-byte pad) 


Texture page ID 

CLUT ID 

Texture vertex coordinates 

Texture vertex coordinates 
Three-dimensional coordinates 

Normal coordinates 

Pointer to start coordinates of a vertex array 
Pointer to start coordinates of a normal array 
Offset to vertex array 

Offset to vertex array 

Offset to normal array 

Offset to normal array 


Some members have no meaning depending on the TMD primitive type. 


See also 
ReadTMD( 
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Functions 





AddPrim, addPrim 
Register a primitive to the OT. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void AddPrim ( 

void “ot OT entry 

void *p) Start address of primitive to be registered 

AddPrim(ot, p) Macro version of AddPrim() 

Explanation 


Registers a primitive beginning with the address *p to the OT entry “ot in OT table. ot is an ordering table or 
pointer to another primitive. 


A primitive may be added to a primitive list only once in the same frame. Attempting to add it multiple times 
in the same frame results in a corrupted list. 


See also 
AddPrims(), CatPrim() 
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AddPrims, addPrims 


Collectively register primitives to the OT. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void AddPrims( 

void “ot, OT entry 

void *00, Start address of primitive list 

void *p7) End address of primitive list 


AddPrims(ot, 00, p1) Macro version of AddPrims 


Explanation 
Registers primitives beginning with pO and ending with p1 to the “ot entry in the OT. 


The primitive list is a list of primitives connected by AddPrim() or created by the local ordering table. 


See also 
AddPrim() 
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BreakDraw 

Interrupt drawing. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.4 12/14/98 

Syntax 


u_long *BreakDraw(void) 


Explanation 


Interrupts drawing after the current polygon is drawn. The return value is the next drawing entry; to resume 
drawing, pass this value to DrawOTag)(). 


Return value 
Next polygon drawing entry. 


However, during a DMA transfer outside the OT (such as Loadimage(), etc.) Oxffffffff is returned. 


See also 
ContinueDraw(), DrawOTag(), IsldleGPU() 
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CatPrim, catPrim 
Concatenate primitives. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void CatPrim( 

void *p0, void *p7) Starting addresses of primitives to be concatenated 

catPrim(00, p1) Macro version of CatPrim() 

Explanation 


Links the primitive p1 to the primitive p0. 


AddPrim() adds a primitive to a primitive list. CatPrim() simply concatenates two primitives. 


Return value 
Start address of pO. 


See also 
AddPrim() 
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CheckPrim 


Check validity of a primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 


Syntax 


long CheckPrim( 
char *s, Pointer to optimal character string 
u_long “p) Pointer to primitive 


Explanation 


Checks the validity of the primitive. If the primitive is found to be invalid, a message is printed with the 
contents of s followed by the type code and length of the primitive. The primitive is not modified in any 
case. 





Return value 
O for a valid primitive; -1 for an invalid primitive. 
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Clearlmage 
Clear Frame Buffer at high speed. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.x 9/1/99 


Syntax 

int Clearlmage( 

RECT "rect, Pointer to rectangular area to be cleared 

u_char r, u_char g, u_char b) Pixel values to be used for clearing 

Explanation 

Sets the rectangular area rect in the Frame Buffer to RGB color values (r, g, b). 

Because this is a non-blocking function, the end of the operation must be detected using DrawSync() or by 


installing a callback with DrawSyncCalloback(). The drawing area is not affected by the drawing environment 
(clip/offset). 


When the width and height of the rectangular area exceeds (w,h)=(1024,512), only the (w,h)=(1023,51 1) 
area is cleared. 


When in interlace mode, use Clearlmage2() instead. 





Return value 
Position of this command in the libgou command queue. 


See also 
Clearlmage2(), DrawSync(), DrawSyncCallback() 


Run-Time Library Reference 


Basic Graphics Library Functions 7-39 


Clearlmage2 

Clear Frame Buffer at high speed (interlace mode). 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.x 9/1/99 

Syntax 

int Clearlmage2( 

RECT "rect, Pointer to rectangular area to be cleared 


u_charr, u_char g, u_char b) Pixel values to be used for clearing 


Explanation 
Sets the rectangular area rect in the Frame Buffer to RGB color values (r, g, b). 


Although Clearlmage() only clears one field when in interlace mode, Clearlmage2() clears both fields. 
However, the DRAWENV.dfe flag will remain high upon completion of this command. This allows drawing 
to both visible and non-visible scan lines. Therefore, after using this function in interlace mode, 
DRAWENV.dfe should be set to O to avoid drawing to both fields. 











Because this is a non-blocking function, the end of the operation must be detected using DrawSync() or by 
installing a callback routine with DrawSyncCallback(). The drawing area is not affected by the drawing 
environment (clip/offset). 


When the width and height of the rectangular area exceeds (w,h)=(1024,512), only the (w,h)=(1023,51 1) 
area is cleared. 


Return value 
Position of this command in the libgou command queue. 


See also 
Clearlmage(), DrawSync(), DrawSyncCallback() 
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ClearOTag 

Initialize an array to a linked list for use as an ordering table. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

u_long *ClearOTag( 

u_long “ot, OT starting pointer 

int n) Number of entries in OT 

Explanation 


Walks the array specified by ot and sets each element to be a pointer to the following element, except the 
last, which is set to a pointer to a special terminator value which the PlayStation® uses to recognize the 
end of a primitive list. n specifies the number entries in the array. 





To execute the OT initialized by ClearOTag(), call DrawOTag(ot). 


See also 
DrawOTag(), ClearOTagR() 
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ClearOTagR 

Initialize an array to a linked list for use as an ordering table. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void ClearOTagR( 

u_long “ot, Head pointer of OT 

long n) Number of entries in OT 

Explanation 


Walks the array specified by ot and sets each element to be a pointer to the previous element, except the 
first, which is set to a pointer to a special terminator value which the PlayStation uses to recognize the end 
of a primitive list. n specifies how many entries are present in the array. 





To execute the OT initialized by ClearOTagR(), execute DrawOTag(ot+n-1). 


See also 
DrawOTag(), ClearOTag() 
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ContinueDraw 

Continue to draw the OT interrupted by BreakDraw() 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void ContinueDraw( 

u_long “inst_ot, Address of interrupting OT 

u_long *cont_ot) Address of drawn OT immediately after drawing inst_ot 

Explanation 


Immediately executes the OT supplied by inst_ot without entering it in the libgou queue. When the drawing 
of inst_ot is completed, it then draws cont_ot. Since the GPU must be in an immediately executable state, 
ContinueDraw() must be used in combination with routines such as BreakDraw(). 


This function is used when you wish to draw a specific OT with certain timing and high priority. In such 
cases, this can be achieved by using BreakDraw/() to interrupt the OT being drawn and by executing the 
return value as cont_ot. 


See also 
BreakDraw() 
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DrawOTag 

Execute a list of GPU primitives. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 

Syntax 

void DrawOTag( 

u_long *oł) Pointer to a linked list of GPU primitives 

Explanation 


Executes the GPU primitives in the linked list ot. 


DrawOTag() is non-blocking. To detect when execution of the primitive list is complete, use DrawSync() or 
install a callback routine with DrawSyncCallback(). 


See also 
DrawSync(), DrawSyncCallback() 
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DrawOTag2 

Execute a list of GPU primitives (immediate execution). 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.1 12/14/98 

Syntax 

int DrawOTag2( 

u_long *p) Pointer to a linked list of GPU primitives 

Explanation 


Executes the GPU primitives in the linked list o. This operation takes place immediately, regardless of what 
is in the GPU queue, and on completion, processing of the queue is resumed. 





When drawing has been suspended using BreakDraw() and you want to execute a linked list of GPU 
primitives using DrawOTag(), immediate execution is not possible because of the need for queueing. If 
immediate execution is desired, you must use DrawOTag2\(). 


When drawing is suspended with BreakDraw() after DrawOTag2() is called, before restarting the drawing 
with ContinueDraw(), it is necessary to confirm the completion of data transfer using IsldleGPU(). This is 
because DrawOTag2() is a non-blocking function. 


Return value 
0: Normal completion; -1: Abnormal completion. 


See also 
BreakDraw(), ContinueDraw(), IsldleGPU(), DrawOTag() 
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DrawOTagEnv 

Set the drawing environment and draw the primitives registered in the OT. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 

Syntax 

void DrawOTagEnv( 

u_long *p, OT start pointer 

DRAWENV *env) Drawing environment 

Explanation 


Sets drawing environment parameters and executes the primitives registered in the OT. 





The drawing environment specified by DrawOTagEnv() is effective until PutDrawEnv(), DrawOTagEnv() or 
the DR_ENV primitive are executed. 


To detect when execution of the primitive list is complete, use DrawSync() or install a callback routine with 
DrawSyncCallback(). 


See also 
PutDrawEnv(), DrawOTagEnv(),DrawSync(), DrawSyncCallback() 
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DrawOTaglO 

Draw the primitives registered in the OT 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.0 12/14/98 

Syntax 

void DrawOTaglO( 

u_long “p) Pointer to top of OT 

Explanation 








Collectively executes the primitives registered in the OT. It is the same as DrawOTag(), except that it uses 
CPU I/O instead of DMA, which results in a significant speed decrease. 


See also 
DrawOTag() 
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DrawPrim 
Draw a primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 

void DrawPrim( 

void *p) Pointer to primitive 
Explanation 


Executes a primitive which has completed initialization. This routine blocks while waiting for all drawing 
commands in the queue to complete, then executes immediately. 


See also 
DrawOTag() 
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DrawSync 

Wait for all drawing to terminate. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

long DrawSync( 

long mode) O: Wait for termination of all non-blocking functions registered in the queue 


1: Return the number of positions in the current queue 


Explanation 
Waits for drawing to terminate. 


If DrawSync(0) is used, and execution of the primitive list takes an exceptionally long time (approximately 
longer than 8 Vsync) to complete, a timeout is generated and the GPU is reset. Reasons why this might 
occur include an exceptionally long primitive list, or one that renders exceptionally large numbers of pixels. 
Another possibility is that the primitive list has been corrupted in some way. To avoid this, the application 
can use a loop such as: 








while (DrawSync(1)); 





The following routines use the GPU queue, and therefore their termination can be detected using 
DrawSync(), or by setting a callback with DrawSyncCallback(): Clearlmage(), Clearlmage2(), DrawOTag\(), 
DrawOTagEnv(), Loadimage(), Movelmage(), PutDrawEnv(), Storelmage(). 


Return value 
Number of positions in the execution queue. 


See also 
DrawSyncCallback() 
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DrawSyncCallback 

Define a callback function to be called when the GPU is finished executing a primitive list. 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 2.X 2/24/99 

Syntax 

u_long DrawSyncCallback( 

void (*func)()) Pointer to calloack function 

Explanation 


Defines a routine to be used as a callback when drawing is completed. When all requests in the queue 
have terminated, the function func is called. If func is set to O, then any previous callback routine is 
disabled. 


Inside the callback, subsequent drawing termination interrupts are masked. Therefore, the callback routine 
should return as soon as possible. Although the specified function is called during an interrupt, it is not an 
interrupt handler; it should be written as a normal subroutine that is called by the main interrupt handler. 


The following routines use the GPU queue, and therefore their termination can be detected using 
DrawSynci(), or by setting a callback with DrawSyncCallback(): Clearlmage(), Clearlmage2(), DrawOTag(), 
DrawOTagEnv(), Loadimage(), Movelmage(), PutDrawEnv(), Storelmage(). 





It is important to note that the callback is called when the GPU queue is empty. If a particular set of 
drawing commands has terminated, but new commands have already been placed in the queue, the 
callback isn’t called until all the commands have terminated. 


Return Value 
Pointer to the previously registered callback function. 


See also 
DrawSync() 
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DumpClut, dumpClut 


Print contents of clut member of primitive. 


Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 2.X 12/14/98 

Syntax 

void DumpClut( 

u_short clut) CLUT ID 

DumpClut(c/ut) Macro version of DumpClut(). 

Explanation 


Prints the CLUT contents. 


See also 
GetClut(), LoadClut() 
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DumpDispEnv 

Print contents of display environment Structure. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void DumpDispEnv( 

DISPENV “env) Pointer to display environment 

Explanation 


Prints the contents of the display environment structure. 
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DumpDrawEnv 

Print contents of drawing environment structure. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void DumpDrawEnv( 

DRAWENV *env) Pointer to drawing environment 

Explanation 


Prints the contents of the drawing environment structure. 


See also 
SetDrawEnv() 
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DumpOTag 

Print primitives registered in the OT. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void DumpOTag( 

u_long “ot) OT starting pointer 

Explanation 


Prints the code fields of the primitives registered in the OT. 


See also 
DrawOTag() 
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DumpTPage, dumpTPage 


Print contents of toage member of primitive. 


Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 2.X 12/14/98 

Syntax 

void DumpTPage( 

u_short tpage) Texture page ID 

DumpTPage(ipage) Macro version of DumpTPage(). 

Explanation 


Prints the contents of the texture page ID. 


See also 
setTPage() 
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FntFlush 

Draw contents of print stream. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

u_long *FntFlush( 

long ia) Print stream ID 

Explanation 


Draws the contents of the print stream into the frame buffer. It initializes and then draws a sprite primitive 
list corresponding to the characters specified in the print stream. 





When id is -1, the print stream ID which was set in SetDumpFnt() is used (0 if print stream ID was not set). 


After the drawing has been done, the print stream contents are also flushed. 


Return value 
The starting pointer of the primitive list used to perform the drawing. 





See also 
SetDumpFnit() 


Run-Time Library Reference 


7-56 Basic Graphics Library Functions 


FntLoad 


Transmit font pattern. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 


void FntLoad( 
long tx, long ty) Font pattern frame buffer address 


Explanation 


Transmits the built-in text font used for debugging text output to the frame buffer. It loads the basic font 
pattern (4-bit, 256x128) and initializes all the print streams. 


FntLoad() must always be executed before FntOpen() and FntFlush(). The font area must not clash with the 
frame buffer area used by the application. Font data is located at the upper left of the texture page for 
FntFlush(). Font data is treated as a RECT (0,0,32,32) area consisting of 128 characters, each 128 x 32. As 
this is similar to the texture page area, tx is restricted to a multiple of 64 and ty is restricted to a multiple of 
256. 


Loads the Clut to location (ix, ty+128). 











See also 
FntOpen(), FntFlush(), SetDumpFnt() 
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FntOpen 

Open a print stream. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 2/24/99 

Syntax 

long FntOpen( 

long x, long y, Display start location 

long w, long h, Display area 

long isbg, Automatic clearing of background 


0: Don’t clear background to (0, 0, 0) when display is performed 
1: Clear background to (0, O, 0) when display is performed 
long n) Maximum number of characters 


Explanation 


Opens the stream for on-screen printing. After this, character strings up to n characters long can be drawn 
in the (x, y)- (x+w, y+h) rectangular area of the frame buffer, using FntPrint(. If isog is 1, the background is 
cleared when a character string is drawn. 





Up to 8 streams can be opened at once. However, once a stream is opened, it cannot be closed until the 
next time FntLoad() is called. 


n specifies the maximum number of characters. Up to 1024 characters can be specified together in 8 
streams. 


Return value 
The stream ID. 


See also 
FntLoad(), FntPrint() 
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FntPrint 
Print a string. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 

long FntPrint( 

long id, Print stream ID 

char *format) Pointer to print format 
Explanation 


Sends the string format to the specified print stream using the same interface as the forintf() standard C 
library function. 


The character string is not actually displayed until FntFlush() has been executed. 


Return value 
The number of characters in the stream. 


See also 
FntOpen(), FntFlush() 
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GetClut, getClut 


Calculate value of the CLUT member in a primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

u_short GetClut( 

int x, int y) Frame buffer address of CLUT 

GetClut(x, y) Macro version of getClut(). 

Explanation 


Calculates and returns the texture CLUT ID. 


The CLUT address is limited to multiples of 16 in the x direction. 


Return value 
CLUT ID. 


See also 
setClut() 
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GetDispEnv 

Get current display environment. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

DISPENV *GetDispEnv( 

DISPENV “env) Pointer to display environment start address 

Explanation 


Stores the current display environment in the address specified by env. 


Return value 
A pointer to the display environment obtained by the function. 


See also 
PutDispEnv(), SetDefDispEnv() 
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Basic Graphics Library Functions 7-61 


GetDrawArea 

Get data for the current draw area. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 

Syntax 

void GetDrawArea( 

DR_AREA *p) Starting address for DR_AREA primitive 

Explanation 


Reads GPU's current draw area settings into p. 


p must be initialized beforehand using SetDrawArea(). 


See also 
SetDrawArea() 
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7-62 Basic Graphics Library Functions 


GetDrawEnv 

Get the current drawing environment. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

DRAWENV *GetDrawEnv( 

DRAWENV “env) Pointer to drawing environment start address 

Explanation 


Stores the current drawing environment in the address specified by env. 


Return value 
env starting address 


See also 
PutDrawEnv(), SetDrawEnv(), GetDrawEnv2() 
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Basic Graphics Library Functions 7-63 


GetDrawEnv2 

Get the current drawing environment. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 4.6 9/1/99 

Syntax 

DR_ENV *GetDrawEnv2( 

DR_ENV p) Pointer to drawing environment change primitive 

Explanation 


Gets the current drawing environment from the GPU and sets the drawing environment change primitive. 
The drawing environments that are obtained are as follows: 

e DR_AREA (Drawing area) 

e DR_OFFSET (Drawing offset) 

e DR_TPAGE (Texture page) 

e DR_TWIN (Texture window) 

e DR_STP (STP bit processing) 


Return value 
None. 


See also 
PutDrawEnv(), SetDrawEnv(),GetDrawEnv() 
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7-64 Basic Graphics Library Functions 


GetDrawMode 

Get current draw mode data 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 

Syntax 

void GetDrawMode( 

DR_MODE *p) Starting address for DR_MODE primitives 

Explanation 


Reads GPU's current draw mode settings into p. 


p must be initialized beforehand with SetDrawMode(). 


See also 
SetDrawMode() 
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Basic Graphics Library Functions 7-65 


GetDrawOffset 


Get the current draw offset. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 


Syntax 


void GetDrawOffset( 
DR_OFFSET *p) Starting address for DR_OFFSET primitive 


Explanation 
Reads GPU's current draw offset settings into p. 


p must be initialized beforehand with SetDrawOffset(). 


See also 
SetDrawOffset() 
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7-66 Basic Graphics Library Functions 


GetGraphDebug 


Get present debug level. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 


Syntax 
int GetGraphDebug(voic) 


Explanation 
Gets graphics system debug level. 


Return value 
Present debug level value. 


See also 
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Basic Graphics Library Functions 7-67 


GetODE 


Get field currently being drawn. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 


Syntax 
int GetODE(voia) 


Explanation 
Gets field currently being drawn. 


Return value 


Current drawing field: 
0: VRAM even address being drawn 
1: VRAM odd address being drawn 
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7-68 Basic Graphics Library Functions 


GetTexWindow 

Get current texture window data. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 

Syntax 

void GetTexWindow( 

DR_TWIN *p) Starting address for DR_TWIN primitives 

Explanation 


Reads GPU's current texture window settings into p. 


p must be initialized beforehand with SetTexWindow(). 


See also 
SetTexWindow() 
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Basic Graphics Library Functions 7-69 


GetTimSize 

Calculate size of Tim data domain returned by Krom2Tim(). 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 3.0 12/14/98 

Syntax 

int GetTimSize( 

u_char “sjis) Pointer to sjis character string 

Explanation 


Calculates size of the Tim data domain returned by Krom2Tim(). This size domain is maintained in malloc() 
and is designated Krom2Tim(). 


Return value 
Size of Tim data domain returned by Krom2Tim(). 


See also 
Krom2Tim() 
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7-70 Basic Graphics Library Functions 


GetTPage, getTPage 


Calculate value of member tpage in a primitive. 


Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 2.X 12/14/98 
Syntax 
u_short GetTPage( 
int to, Texture mode 
0: 4bitCLUT 
1: 8bitCLUT 
2: 16bitDirect 
int abr, Semitransparency rate 


0: 0.5 x Back + 0.5 x Forward 

1: 1.0 x Back + 1.0 x Forward 

2: 1.0 x Back - 1.0 x Forward 

3: 1.0 x Back + 0.25 x Forward 
int x, int y) Texture page address 


getTPage((tp, abr, x, y) Macro version of GetTPage(). 


Explanation 
Calculates the texture page ID, and returns it. 





The semitransparent rate is also effective for polygons on which texture mapping is not performed. 


The texture page address is limited to a multiple of 64 in the X direction and a multiple of 256 in the Y 
direction. 





Return value 
Texture page ID. 


See also 
setTPage(), DumpTPage() 
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Basic Graphics Library Functions 7-71 


IsEndPrim, isendprim 
Determine if a primitive is the last in a list. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

int IsEndPrim( 

void *p) Primitive start address 

isendprim(o) Macro version of IsEndPrim(). 

Explanation 


Decides if the end of the primitive list is p. 


Return value 
1: final end case; 0: non-final end case. 


See also 
AddPrim() 
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7-72 Basic Graphics Library Functions 


IsldleGPU 

Check if drawing suspended by BreakDraw() was completed. 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 3.6 12/14/98 

Syntax 

int IsldleGPU( 

int maxcount) Count value 

Explanation 





Checks whether the GPU is idle. 


When drawing is suspended by BreakDraw(), the GPU doesn’t stop until drawing of the current primitive is 
completed. This function checks whether the drawing suspended by BreakDraw() has completed. 
maxcount is the number of times the function will check for idle before returning. 


Return value 
0: GPU is in idle state. -1: GPU is in drawing state. 


See also 
BreakDraw() 
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Basic Graphics Library Functions 7-73 


KanjiFntClose 

Close print streams. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 

Syntax 


void KanjiFntClose(voic) 


Explanation 


Closes all the streams currently open and are by KanjiFntPrint() and initializes the state of the Kanji font 
ruoutines. It will function correctly even when no streams are open. 





See also 
KanjiFntFlush(), KanjiFntOpen(), KanjiFntPrint() 
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7-74 Basic Graphics Library Functions 


KanjiFntFlush 

Draw contents of a Kanji print stream. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 

Syntax 

u_long *KanjiFntFlush( 

int id) Print stream ID 

Explanation 


Draws the contents of the Kanji print stream into the frame buffer. It initializes and then draws a sprite 
primitive list corresponding to the characters specified in the print stream. 





The contents of a print stream are also flushed after the end of drawing. 


To internally reserve the transfer buffer on the stack, approximately 72K is needed. 





Return value 
Start pointer of a primitive list used for drawing 


See also 
KanjiFntClose(), KanjiFntOpen(), KanjiFntPrint() 
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Basic Graphics Library Functions 7-75 


KanjiFntOpen 

Open a print stream. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 2/24/99 

Syntax 

int KanjiFntOpen( 

int x, int y, Position of starting display 

int w, int h, Display area 

int dx, int ay, Kanji font pattern frame buffer address 

int cx, int cy, Kanji clut frame buffer address 

int /sbg, Automatic background clear 


O: Does not clear the background to (0, O, 0) during display 
1: Clears the background to (0, O, 0) during display 
int n) Maximum number of characters 


Explanation 


Opens a stream for screen printing. Then, KanjiFntPrint() can be used to render a character string 
composed of up to n characters in the rectangular area of (x, y) and (x+w, y+h) in the frame buffer. With 
isbg assigned a value of one, the background is cleared when a character string is rendered. 





Up to four streams can be opened at a time, and a maximum of 256 characters can be specified in one 
stream. The kanji font area must not interfere in the frame buffer area used for applications. 





With ax and dy, the address in the upper left of the texture page must be specified. 


Return value 
Stream ID. 


See also 
KanjiFntClose(), KanjiFntFlush(), KanjiFntPrint() 


Run-Time Library Reference 


7-76 Basic Graphics Library Functions 


KanjiFntPrint 

Print a string, in SUIS ZENKAKU format. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 3.0 12/14/98 

Syntax 

int KanjiFntPrint( 

int id, Print stream ID 

char *format, [arg]...) Pointer to print format 

Explanation 


Send SUIS ZENKAKU string using printf() interface. 


KANJI code must be the SJIS. Although both ZENKAKU and HANKAKU characters can be mixed in the 
string, a HANKAKU character is converted to ZENKAKU when it is drawn. HANKAKU KANA characters are 
not supported. Actual drawing of the string is done at execution of KanjiFntFlush(). When there is ~p in the 
string format, all the characters after ~p are drawn in half-pitch. 


Return value 
Number of characters within the stream. 


See also 
KanjiFntClose(), KanjiFntFlush(), KanjiFntOpen() 
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Basic Graphics Library Functions 7-77 


Krom2Tim 

Convert SJIS character string to 4-bit CLUT Tim data. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 

Syntax 

int Krom2Tim ( 

u_char “sjis, SJIS character string 

u_long “tadar, Tim area for storing data 

int dx, int dy, Pixel data x,y coordinates on VRAM 

int cdx, int cay, Clut data x,y coordinates on VRAM 

u_int fg, u_int bg) Character color and bg color 

Explanation 


Converts SJIS character string to 4 bits CLUT TIM data and returns it to tadar. 





The size area returned by GetTimSize() must be secured in advance. 


The Kanji code must be SuJIS. Full-width and half-width characters can be mixed within the character string, 
but when they are displayed, they area Il converted to full-width characters. Half-width characters are not 
supported. 





To internally reserve the transfer buffer on the stack, approximately 72K is needed. 





Return value 
When an abnormal code is given, -1 is returned; O otherwise. 





See also 
GetTimSize() 
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7-78 Basic Graphics Library Functions 


LoadClut 
Load 256-color CLUT. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 


u_short LoadClut( 
u_long “clut, Pointer to CLUT data start address 
long x, long y) Destination coordinates in frame buffer 


Explanation 


Loads 256 entries of texture color data (CLUT) from main memory address clut into the frame buffer (x,y) 
and calculates the ID of the loaded texture CLUT. 


256 palette entries are always transmitted, even in 4-bit mode. 


Return value 
The CLUT ID for the loaded CLUT. 


See also 
LoadClut2() 
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Basic Graphics Library Functions 7-79 


LoadClut2 
Load 16-color CLUT. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 


Syntax 

u_short LoadClut2( 

u_long “clut, Texture color start address 

int x, int y) Destination frame buffer address 

Explanation 

Loads 16 entries of texture color data (CLUT) from main memory address clut into the frame buffer (x,y) and 
calculates the ID of the loaded texture CLUT. 


LoadClut2() transmits 16 palette entries whereas LoadClut() transmits 256 palette entries. 





LoadClut2() internally invokes Loadimage(). 


Return value 
The CLUT ID for the loaded CLUT. 


See also 
LoadClut(), Loadlmage() 
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7-80 Basic Graphics Library Functions 





Loadimage 

Transfer data to a frame buffer. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

int LoadImage( 

RECT *recp, Pointer to destination rectangular area 

u_long *p) Pointer to main memory address of source of transmission 

Explanation 

Transfers the contents of memory from the address p to the rectangular area in the frame buffer specified 

by recp. 


Because Loadimage() is a non-blocking function, transmission termination must be detected by DrawSync() 
or by installing a callback routine with DrawSyncCallback(). 





The source and destination areas are not affected by the drawing environment (clip, offset). The destination 
area must be located within a drawable area (0, 0) - (1028, 511). See the description of the DR_LOAD 
primitive. 


Return value 
Position of this command in the libgou command queue. 


See also 
DrawSync(), DrawSyncCallback(), Loadlmage2(), Storelmage(), 
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Basic Graphics Library Functions 7-81 





LoadIimage2 

Transfer data to a frame buffer (immediate execution). 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 4.1 12/14/98 

Syntax 

int Loadlmage2( 

RECT "rect, Pointer to destination rectangular area 

u_long *p) Pointer to main memory address of source of transfer 

Explanation 


Transfers the contents of memory beginning at the address pointed to by p to the rectangular area in the 
frame buffer specified by rect, without queueing. This operation takes place immediately, regardless of 
what is in the GPU queue, and on completion, processing of the queue is resumed. 





When drawing has been suspended using BreakDraw() and you want to transfer data to the frame buffer 
using Loadimage(), immediate execution is not possible because of the need for queueing. If immediate 
execution is desired, you must use Loadimage2(). 





The drawing area (clip offset) does not affect the transfer area. 
The destination area must be located within a drawable area (0, O) - (1023, 511). 


When drawing is suspended with BreakDraw() after Loadimage2() is called, before restarting the drawing 
with ContinueDraw(), it is necessary to confirm the completion of data transfer using IsldleGPU(). This is 
because Loadimage2() is a non-blocking function. 


Return value 
0: Normal completion; -1: Abnormal completion. 


See also 
BreakDraw(), ContinueDraw(), IsldleGPU(), Loadimage() 
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7-82 Basic Graphics Library Functions 





LoadTPage 

Load a texture page. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

u_short LoadTPage( 

u_long “pix, Pointer to texture pattern start address 

int to, Bit depth (0 = 4-bit; 1 = 8-bit; 2 = 16-bit) 

int abr, Semitransparency rate 

int x, int y, Destination frame buffer address 

int w, int h) Texture pattern size 

Explanation 





Loads a texture pattern from the memory area starting at the address pix into the frame buffer area starting 
at the address (x, y), and calculates the texture page ID for the loaded texture pattern. 





The texture pattern size w represents the number of pixels, not the actual size of the transfer area in the 
frame buffer. 


LoadTPage() calls Loadimage() internally. 


Return value 
Texture page ID for the loaded texture pattern. 


See also 
Loadimage(), setTPage() 
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Basic Graphics Library Functions 7-83 


MargePrim 
Link primitives. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 3.0 12/14/98 


Syntax 

int MargePrim( 

void *00, First primitive 

void *p7) Second primitive 

Explanation 

Links primitive pO to primitive p7. The combined primitive size of p0 and p1 must be less than 15 words. 
Within this size, any number of connections is possible. 


The resulting linked primitives can be added to an OT using AddPrim(). 





pO and p1 describe continuous regions of memory. p1 must be the higher address. 


Return value 
O on success, -1 on failure. 


See also 
AddPrim() 
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7-84 Basic Graphics Library Functions 


Movelmage 

Transfer data between two locations within the frame buffer. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

int Movelmage( 

RECT rect, Pointer to source rectangular area 

int x, int y) Top left corner of the destination rectangle 

Explanation 


The rectangular area of the frame buffer specified by rect is copied to the rectangular area of the same size 
starting at (x, y). 














The content at the source is preserved. If the source and destination areas are the same, normal operation 
is not guaranteed. 





Because Movelmage() is a non-blocking function, the end of copying must be detected by DrawSync() or 
by installing a callback routine with DrawSyncCallback(). 





Note: Depending on the timing, there are cases when Movelmage() fails to execute when multiple 
Movelmage() functions are executed while a movie is playing. In such cases, it is necessary to wait for the 
transfer to terminate by calling DrawSync() after each Movelmage(). 








The source and destination areas are not affected by the drawing environment (clip, offset). The destination 
area must be located within a drawable area (O, 0) - (1023, 511). See also the description of the DR_-MOVE 
primitive. 


Return value 
Position of this command in the libgou command queue. 


See also 
DrawSync(), DrawSyncCallback(), Loadlmage(), Movelmage2() 
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Basic Graphics Library Functions 7-85 





Movelmage2 

Transfer data between two locations within the frame buffer (immediate execution). 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 4.1 12/14/98 

Syntax 

int Movelmage2( 

RECT rect, Pointer to source rectangular area 

int x, y) Top left corner of the destination rectangle 

Explanation 





The rectangular area of the frame buffer specified by rect is transferred to the rectangular area of the same 
size starting at (x, y). This operation takes place immediately, regardless of what is in the GPU queue, and 
on completion, processing of the queue is resumed. 


The contents of the source rectangle are preserved. If the source and destination areas are the same, 
normal operation is not guaranteed. 








When drawing is suspended with BreakDraw() and you want to move data within the frame buffer using 
Movelmage(), immediate execution is not possible because of the need for queueing. If immediate 
execution is desired, you must use Movelmage2(). 





The source and destination transfer areas are not affected by the drawing environment (clip, offset). The 
source and destination areas must be located within a drawable area (O, 0) - (1023, 511). See also the 
description of the DR_MOVE primitive. 





When drawing is suspended with BreakDraw() after Movelmage2() is called, before restarting the drawing 
with ContinueDraw(), it is necessary to confirm the completion of data transfer using IsldleGPU(). This is 
because Movelmage2() is a non-blocking function. 





Return value 
0: Normal completion; -1: Abnormal completion.. 


See also 
BreakDraw(), ContinueDraw(), IsldleGPU(), Movelmage() 
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7-86 Basic Graphics Library Functions 


NextPrim, nextPrim 
Get pointer to next primitive in primitive list. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void *NextPrim( 

void *p) Pointer to start address of a primitive 

nextPrim/(p) Macro version of NextPrim() 

Explanation 


Returns a pointer to the next primitive in a primitive list. 


Return value 
Pointer to the next primitive. 


See also 
AddPrim() 
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Basic Graphics Library Functions 7-87 


OpenTIM 
Open TIM data. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 


long OpenTIM( 
u_long “addr Pointer to main memory address to which the TIM has been loaded 


Explanation 
Opens a TIM in main memory. The information in the opened TIM can then be read using ReadTIM(). 


Only one TIM can be opened at a time. An opened TIM is not closed until the next time OpenTIM() is called. 


Return value 
O on success; any other value indicates failure. 


See also 
ReadTIM() 
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7-88 Basic Graphics Library Functions 


OpenTMD 
Open TMD data. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 


long OpenTMD( 
u_long *tmd, Pointer to main memory address to which TMD has been loaded 
long obj_no) Object number 


Explanation 


Opens the TMD of the object specified by obj/_no. The information in the opened TMD can then be read 
using ReadTMD(). 


Calling OpenTMD( closes any previously opened TMD. 


Return value 
The number of polygons comprising the object as a positive integer; on failure, returns O. 


See also 
ReadTMD() 
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PutDispEnv 


Set the display environment. 


Library Header File Introduced 
libgpu. lib libgpu.h 2.X 


Syntax 

DISPENV *PutDispEnv( 

DISPENV *env) Pointer to display environment start address 
Explanation 

Sets a display environment according to information specified by env. 


Return value 
A pointer to the display environment set; on failure, returns O. 


See also 
GetDispEnv(), SetDefDispEnv(), SetDefDispEnv() 


Basic Graphics Library Functions 7-89 


Documentation Date 
12/14/98 
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7-90 Basic Graphics Library Functions 


PutDrawEnv 
Set the drawing environment. 


Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 2.X 12/14/98 


Syntax 

DRAWENV *PutDrawEnv( 

DRAWENV “env) Pointer to drawing environment start address 

Explanation 

The basic drawing parameters (such as the drawing offset and the drawing clip area) are set according to 
the values specified in env. 


The drawing environment is effective until the next time PutDrawEnv() is executed, or until the DR_LENV 
primitive is executed. 





Return value 
A pointer to the drawing environment set. On failure, returns 0. 


See also 
DrawOTagEnv(), GetDrawEnv(), SetDefDrawEnv(), SetDrawEnv() 
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Basic Graphics Library Functions 7-91 


ReadTIM 
Produce TIM header. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 

TIM_IMAGE *ReadTIM( 

TIM_IMAGE *timimg) TIM_IMAGE structure pointer 
Explanation 


Sets the members of the TIM_IMAGE structure pointed to by timimg according to the data specified by the 
most recent OpenTIM() call. 


Return value 
The timimg start address, if succesful; O if TIM analysis fails. 


See also 
OpenTim() 


Run-Time Library Reference 


7-92 Basic Graphics Library Functions 


ReadTMD 

Read contents of TMD primitives. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 2/24/99 

Syntax 


TMD_PRIM *ReadTMD( 
TMD_PRIM *tmadprim) Pointer to printer for TMD-PRIM structure 


Explanation 


Sets the members of the TMD_PRIM structure pointed to by tmaprim according to the data specified by 
the most recent OpenTMD)() call. 


Note that the TMD_PRIM structure includes fields that are not used for all types of objects. ReadTIM() 
copies only those fields that are valid for the current object. 


Gradation system primitives are not supported. 


Return value 
tmadprim if successful; O on failure. 


See also 
OpenTMD() 
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Basic Graphics Library Functions 7-93 


ResetGraph 


Initialize drawing engine. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 


Syntax 

int ResetGraph( 

int mode) Reset mode 
Explanation 

Resets the graphic system according to mode: 








Table 7-3 
Mode Operation 
O Complete reset. The drawing environment 
and display environment are initialized. 
1 Cancels the current drawing and flushes 
the command buffer. 
3 Initializes the drawing engine while 


preserving the current display environment 
(i.e. the screen is not cleared or the screen 
mode changed). 
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7-94 Basic Graphics Library Functions 


SetDefDispEnv 

Set display environment structure members and screen display area. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

DISPENV 

*SetDefDispEnv( 

DISPENV “disp, Pointer to display environment 

int x, int y, Upper left corner of display area 

int w, int h) Width and height of the display area 

Explanation 


Sets the members of a DISPENV (display environment) structure. The new display area is specified using 
the coordinates within the frame buffer of the top left corner, along with the width and height, of the desired 











rectangle. 

Table 7-4 
Member Content Value 
disp Display area (x, y, w, h) 
screen Screen display area (O, 0)-(0, 0) 
isinter Interlace flag O 
isrgbo24 24-bit mode flag 0 








This function does not actually change the display environment. It merely sets the members of the specified 
structure as desired. Use PutDispEnv() with this structure to change the actual environment. 





Note: While the screen width and height are set to (O, 0), internally they are processed as (256, 240). 


Return value 
Pointer to the display environment set. 


See also 
GetDispEnv(), PutDispEnv() 
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Basic Graphics Library Functions 7-95 


SetDefDrawEnv 

Set standard drawing environment structure. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

DRAWENV *SetDefDrawEnv( 

DRAWENV “env, Pointer to drawing environment 

int x, int y, Upper left corner of drawing area 

int w, int h) Width and height of drawing area 

Explanation 


Sets the drawing area members of a DRAWENV (drawing environment) structure. The new drawing area is 
specified using the coordinates within the frame buffer of the top left corner, along with the width and 
height, of the desired rectangle. 














Table 7-5 
Member Content Value 
clip Drawing area (x, y, w, h) 
ofs[2] Drawing offset (x, y) 
tw Texture window (0, O, 0, 0) 
tpage Texture page (tp, abr, tx, ty) (0, 0, 640, 0) 
dtd Dither processing flag 1 (ON) 
dfe Permission flag for drawing 1 (drawing on display area 

is inhibited) 

isbg Draw area clear flag O (clear: OFF) 
rO, gO, bO Background color (0, 0, 0) 





This function does not actually change the drawing environment. It merely sets the members of the 
specified structure as desired. Use PutDrawEnv() with this structure to change the actual environment. 


Return value 
The starting pointer of the drawing environment set. 


See also 
GetDrawEnv(), PutDrawEnv(), SetDrawEnv() 
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7-96 Basic Graphics Library Functions 


SetDispMask 

Set and cancel display mask. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDispMask( 

int mask) Display mask 

Explanation 


Puts display mask into the status specified by mask. mask =0: not displayed on screen; mask = 1; 
displayed on screen. 
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SetDrawArea 

Initialize content of drawing area setting primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawArea( 

DR_AREA *p, Pointer to drawing area setting primitive 

RECT *) Pointer to drawing area 

Explanation 


Initializes a DR_LAREA primitive. By using AddPrim() to insert a DR_AREA primitive into your primitive list, it is 
possible to change part of your drawing environment in the middle of drawing. 


See also 
AddPrim(), GetDrawArea() 
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7-98 Basic Graphics Library Functions 


SetDrawEnv 

Initialize content of drawing environment change primitive. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawEnv( 

DR_ENV “ar_env, Pointer to drawing environment change primitive 

DRAWENV “env) Pointer to drawing environment structure in which the drawing environment 

is described 
Explanation 


Initializes a DR_ENV primitive using the values contained in a DRAWENYV structure. By using AddPrim() to 
insert a DR_ENV primitive into your primitive list, it is possible to change part of your drawing environment 
in the middle of drawing. 


The DR_ENV primitive uses the same information as the DRAWENYV structure, but the data format is 
different and the DRAWENV structure cannot be used as a primitive. When the DR_ENV primitive is 
executed, the previous drawing environment settings are destroyed. 





See also 
AddPrim(), GetDrawEnv(), PutDrawEnv(), SetDefDrawEnv() 
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Basic Graphics Library Functions 7-99 


SetDrawLoad 

Initialize content of the Loadimage primitive. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawLoad( 

DR_LOAD *p, Destination rectangular area primitive 

RECT *rect) Destination rectangular area 

Explanation 


Initializes the destination rectangular area primitive. By registering the initialized primitive in OT using 
AddPrim(), the rectangular area can be transferred just as in Loadimage(). 


Maximum data transfer amount is 12 words (24 pixels). 


See also 
AddPrim(), Loadimage() 
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7-100 Basic Graphics Library Functions 


SetDrawMode, setDrawMode 
Initialize content of a drawing mode primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.x 9/1/99 
Syntax 
void SetDrawMode( 
DR_MODE *p, Pointer to drawing mode primitive 
int dfe, O: drawing not allowed in display area, 
1: drawing allowed in display area 
int dtd, O: dithering off, 1: dithering on. 
int toage, Texture page 
RECT *tw) Pointer to texture window 


setDrawMode (p, dfe, did, toage, tw) Macro version of SetDrawMode() 


Explanation 


Initializes a DR_MODE primitive. By using AddPrim() to insert a DR_MODE primitive into your primitive list, it 
is possible to change part of your drawing environment in the middle of drawing. 


If tw is O, the texture window is not changed. 


See also 
GetDrawMode() 
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Basic Graphics Library Functions 7-101 


SetDrawMove 

Initialize rectangle copy primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawMove( 

DR_MOVE *p, Pointer to rectangular area copy primitive 

RECT *rect, Rectangular area to be transferred 

int x,y) Upper left edge of the rectangular area transfer destination 

Explanation 


Initializes the rectangular area copy primitive. After the primitive is initialized, it can be entered in the OT 
using AddPrim(). When the primitive is executed, it performs the same copying of a rectangular area as 
Movelmage(). 





See also 
AddPrim(), Movelmage() 
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7-102 Basic Graphics Library Functions 


SetDrawOffset 

Initialize drawing offset setting primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawOffset( 

DR_OFFSET *p, Pointer to drawing offset setting primitive 

u_short “ofs) Pointer to drawing offset 

Explanation 


Initializes a DR_OFFSET primitive. By using AddPrim() to insert a DR_OFFSET primitive into your primitive 
list, it is possible to change part of your drawing environment in the middle of drawing. 


See also 
AddPrim(), GetDrawOffset() 
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Basic Graphics Library Functions 7-103 


SetDrawStp 

Initializes STP bit update primitive. 
Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 4.1 12/14/98 

Syntax 

void SetDrawSitp( 

DR_STP “p, Pointer to primitive 

int obw) STP bit update flag (0: STP bit OFF, 1: STP bit ON) 

Explanation 


Initializes the DR_STP primitive pointed to by p. 


When pbw = 0, normal drawing is performed. When pbw = 1, drawing is performed with the STP bit set 
(STP is a 16-bit object). 
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7-104 Basic Graphics Library Functions 


SetDrawTPage, setDrawTPage 


Initialize texture page change primitive. 





Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDrawTPage( 

DR_TPAGE “p, Texture page setting primitive 

int dfe, Flag for drawing to a display area 


0: no drawing in display area 
1: drawing in display area 
int dtd, Dither processing flag 
O: dither processing not performed 
1: dither processing performed 
int toage) Texture page 


setDrawTPage(p, dfe, dtd, toage) Macro version of SetDrawTPage(). 


Explanation 


Initializes a texture page change primitive. By registering the initialized primitive in OT using AddPrim(, the 
texture page can be changed while drawing. 








See also 
AddPrim(), setTPage() 
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Basic Graphics Library Functions 7-105 


SetDumpFnt 

Define stream for onscreen dump. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetDumpFnt( 

long ia) Print stream ID 

Explanation 


Sets the print stream for debug printing. The output of the debug printing functions can then be carried out 
in relation to the stream specified in id. 


The actual display is executed by FntFlush(). 


See also 
dumpRECT(), dumpMatrix(), dumpVector(), dump...(), FntFlush() 
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7-106 Basic Graphics Library Functions 


SetGraphDebug 
Set debugging level. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 

void SetGraphDebug( 

int /evel) Debugging level 

Explanation 

Sets a debugging level for the graphics system. level can be one of the following: 








Table 7-6 

Level Operation 

O No checks are performed. (Highest speed 
mode) 

1 Checks coordinating registered and drawn 
primitives. 

2 Registered and drawn primitives are 
dumped. 





Return value 
The previously set debug level. 


See also 
GetGraphDebug() 
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Basic Graphics Library Functions 7-107 


SetLineF2, SetLineF3, SetLineF4; 
setLineF2, setLineF3, setLineF4; 
SetLineG2, SetLineG3, SetLineG4; 
setLineG2, setLineG3, setLineG4 


Initialize a line primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Syntax 
void SetLineF2(LINE_F2 *p) Flat unconnected straight line drawing primitive. 
void SetLineF3(LINE_F3 *p) Flat connected 2-straight line drawing primitive. 
void SetLineF4(LINE_F4 *p) Flat connected 8-straight line drawing primitive. 
void SetLineG2 (LINE _G2 *p) Gouraud unconnected straight line drawing primitive. 
void SetLineG3 (LINE_G3 *p) Gouraud connected 2-straight line drawing primitive. 
void SetLineG4 (LINE_G4 *p) Gouraud connected 8-straight line drawing primitive. 
setLineF2(p) Macro version of SetLineF2() 
setLineF3(0) Macro version of SetLineF3\() 
setLineF4(p) Macro version of SetLineF4(). 
setLineG2(p) Macro version of SetLineG2() 
setLineG3(p) Macro version of SetLineG3() 
setLineG4(p) Macro version of SetLineG4() 
Explanation 


These functions initialize the primitives specified by p. 


See also 
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7-108 Basic Graphics Library Functions 


SetPolyF3, SetPolyF4; 
setPolyF3, setPolyF4; 
SetPolyG3, SetPolyG4; 
setPolyG3, setPolyG4; 
SetPolyGT3, SetPolyGT4; 
setPolyGT3, setPolyGT4 


Initialize a polygon primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetPolyF3(POLY_F3 *p) Flat shaded triangle primitive. 

void SetPolyF4(POLY_F4 *p) Flat shaded quadrangle primitive. 


void SetPolyFT3(POLY_FT3 *p) Flat textured triangle primitive. 

void SetPolyFT4(POLY_FT4 *p) Flat textured quadrangle primitive. 
void SetPolyG3(POLY_G3 *p) Gouraud shaded triangle primitive. 
void SetPolyG4(POLY_G4 *p) Gouraud shaded quadrangle primitive. 
void SetPolyGT3(POLY_GT3 *o) Gouraud textured triangle primitive. 
void SetPolyGT4(POLY_GT4 *o) Gouraud textured quadrangle primitive. 


setPolyF3(p) Macro version of SetPolyF3() 
setPolyF4(p) Macro version of SetPolyF4() 
setPolyFT3(p) Macro version of SetPolyFT3() 
setPolyFT4(p) Macro version of SetPolyFT4() 
setPolyG3(p) Macro version of SetPolyG3\() 
setPolyG4(p) Macro version of SetPolyG4() 
setPolyGT3(p) Macro version of SetPolyGT3\() 
setPolyGT4(p) Macro version of SetPolyGT4() 
Explanation 


These functions initialize the primitive specified by p. 


See also 
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Basic Graphics Library Functions 7-109 


SetSemiTrans, setSemiTrans 
Set the semitransparent attribute of a primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetSemiTrans( 

void *p, Pointer to primitive 

int abe) Semitransparent flag 


0: semitransparent OFF 
1: semitransparent ON 


setSemiTrans(p, abe) Macro version of SetSemiTrans() 


Explanation 


Sets the semitransparent attribute of the primitive specified by p to the value specified by abe. If 
semitransparent mode is enabled, then semitransparent pixels are drawn as specified by the table below. 








Table 7-7 

Primitive Pixels subjected to semitransparent 
processing 

POLY_FT8/POLY_FT4 Pixels for which the topmost bit of the 
corresponding texture pixel is 1 

POLY_GT8/POLY_GT4 Pixels for which the topmost bit of the 
corresponding texture pixel is 1 

SPRT/SPRT_8/SPRT_16 Pixels for which the topmost bit of the 
corresponding texture pixel is 1 

Other drawing primitives All Pixels 





Semitransparent pixels are calculated from the foreground pixels Pf and background pixels Pb as follows: 


P =F x Pf + B x Pb 





The rate (F, B) of semitransparency is designated by the member tpage in the primitive. Drawing speed is 
reduced because semitransparency requires reading of background brightness values. Therefore, do not 
draw primitives with semitransparent mode turned on unless they are to be displayed that way. 
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7-110 Basic Graphics Library Functions 


SetShadeTex, setShadeTex 


Inhibit shading function. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetShadeTex( 

void *p, Pointer to primitive 

int tge) Unshaded flag 


O: Shading is performed 
1: Shading is not performed 


setShadeTex(p, tge) Macro version of SetShadeTex() 
Explanation 
Sets the shading attribute of the primitive pointed to by p to the value specified by tge. 


When texture and shading are both ON, each pixel in the polygon is calculated as shown below from the 
pixel value T of the corresponding texture pattern, and the brightness value L corresponding to the pixel 








value T. 
P = (T&0x£8*L&0x£8) / 128 
if (p > 255) p = 255 
if (p < 0) p = 0 


When L = 128, the brightness value of the texture pattern is drawn as it is. If the value results in an 
overflow, the pixel value is clipped to 255. 





When tge = 1, the brightness value is not divided, and the texture pattern value is used, as it is, as the pixel 
value. 











T, L are only effective for the upper 5 bits. The lower 3 bits are discarded. 


This function cannot be used for primitives other than POLY_FT38, POLY_FT4, SPRT, SPRT_8, and 
SPRT_16. 


Although the texture number of colors is saved at intensity level of 32 when using ShadeTex, the shading 
brightness value is decreased from an intensity level of 256 to 32. 
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Basic Graphics Library Functions 7-111 


SetSprt, SetSprt8, SetSprt16; 
setSprt, setSprt8, setSprt16 


Initialize a sprite primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetSprt(SPRT *p) Initialize a SPRT primitive. 

void SetSprt8(SPRT_8 *p) Initialize a SPRT8 primitive. 

void SetSprt16(SPRT_16 *p) Initialize a SPRT16 primitive. 

setSprt(o) Macro version of SetSprt() 

setSprt8(o) Macro version of SetSprt8() 

setSprt16(o) Macro version of SetSprt16() 

Explanation 


These functions initialize the primitives specified by p. Details are given below. 








Table 7-8 
Function name Sprite size Primitive 
SetSprts 8x8 SPRT_8 
SetSprt16 16x 16 SPRT_16 
SetSprt Can be set using values of = SPRT 


members h, w. 
(O< h< 255, 0 <w < 255) 





The SPRT... primitives are faster than POLY_FT4. TILE is also faster than POLY_F4. 
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7-112 Basic Graphics Library Functions 


SetTexWindow 

Initialize the content of a texture window primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

void SetTexWindow( 

DR_TWIN “p, Pointer to texture window primitive 

RECT *tw) Pointer to texture window 

setTexWindow(p, tw) Macro version of SetTexWindow() 

Explanation 


Initializes a DR_TWIN primitive using the specified values. By using AddPrim() to insert a DR_TWIN primitive 
into your primitive list, it is possible to change the current texture window in the middle of drawing. 





See also 
AddPrim(), GetTexWindow() 
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Basic Graphics Library Functions 7-113 


SetTile, SetTile1, SetTile8, SetTile16; 
setTile, setTile1, setTile8, setTile16 


Initialize a tile primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 

Syntax 

void SetTile(TILE *p) Initialize a TILE primitive. 

void SetTile1(TILE_1 *p) Initialize a TILE1 primitive. 

void SetTile8(TILE_8 *p) Initialize a TILE8 primitive. 

void SetTile16(TILE_16 *p) Initialize a TILE16 primitive. 

setTile(p) Macro version of SetTile() 

setTile (0) Macro version of SetTile1 () 

setTile8(p) Macro version of SetTile8() 

setTile1 6(p) Macro version of SetTile16() 

Explanation 


These functions initialize the primitives specified by p. Details are given below. 








Table 7-9 
Function name Tile size Primitive size 
SetTile1 1x1 TILE_1 
SetTile8 8x8 TILE_8 
SetTile16 16x16 TILE_16 
SetTile Can be set using values of TILE 


members h, w. 
(O< h< 255, 0 <w < 255) 





The SPRT primitives are faster than POLY_FT4. TILE is also faster than POLY_F4. 
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7-114 Basic Graphics Library Functions 


Storelmage 

Transfer image data from the frame buffer to main memory. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

int Storelmage( 

RECT *recp, Pointer to destination rectangular area 

u_long *p) Pointer to main memory address of destination of transmission 

Explanation 


Transfers the rectangular area of the frame buffer specified by reco to the main memory storage location 
starting at the address specified by p. 


Because Storelmage() is a non-blocking function, use DrawSync() to determine when the operation has 
completed, or install a callback with DrawSyncCallback(). 








The source and destination areas are not affected by the drawing environment (clip, offset). The source 
area must be located within a drawable area (0, O) - (1023, 511). 


Return value 
Position of this command in the libgou command queue. 


See also 
Storelmage2(), DrawSync(), DrawSyncCallback(), Loadlmage() 
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Basic Graphics Library Functions 7-115 


Storelmage2 

Transfer data from a frame buffer (immediate execution). 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.1 12/14/98 

Syntax 

int Storelmage2( 

RECT rect, Pointer to source rectangular area 

u_long *p) Pointer to destination main memory address 

Explanation 


Transfers the contents of the rectangular area in the frame buffer pointed to by rect to the main memory 
location starting with the address pointed to by p, without queueing. p must be on a word boundary. This 
operation takes place immediately, regardless of what is in the GPU queue, and on completion, processing 
of the queue is resumed. 





When drawing is suspended with BreakDraw(), and you want to transfer data from the frame buffer using 
Storelmage(), immediate execution is not possible because of the need for queueing. If immediate 
execution is desired, you must use Storelmage2(). 


The drawing area (clip offset) does not affect the transfer area. 
The transfer area must be located within a drawable area (0, 0) - (1023, 511). 


When drawing is suspended with BreakDraw() after Storelmage2() is called, before restarting the drawing 
with ContinueDraw(), it is necessary to confirm the completion of data transfer using IsldleGPU(). This is 
because Storelmage2() is a non-blocking function. 





Return value 
0: Normal completion. -1: Abnormal completion. 


See also 
BreakDraw(), ContinueDraw(), IsldleGPU(), Storelmage(), Loadlmage() 
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7-116 Basic Graphics Library Functions 


TermPrim, termPrim 
Terminate a primitive list 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2X 12/14/98 

Syntax 

void TermPrim( 

void *p) Pointer to start address of a primitive list 

termPrim(p) Macro version of TermPrim() 

Explanation 


Sets the tag pointer of the primitive specified by p to point at a special terminator value that signals the end 
of the list when it is executed. Any primitives already pointed to by p are removed from the list. 


See also 
CatPrim(), MargePrim( 
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Basic Graphics Library Functions 7-117 


VSync 

Wait for the next vertical blank, or return the vertical blank counter value. 
Library Header File Introduced Documentation Date 
libetc.lib libetc.h 2.X 03/06/00 

Syntax 

int VSync( 

int mode) Mode 

Explanation 


Waits for vertical blank using the method specified by mode, as defined below. 








Table 7-10 
Mode Operation 
(0) Blocks until vertical sync is generated 
1 Returns time elapsed from the point 


VSync() processing is last completed 
when mode=0 or n in horizontal sync units 
n (n>1) Blocks from the point VSync() processing 
is last completed when mode=0 or n until 
n number of vertical syncs are generated. 
-n (n>0) Returns absolute time after program boot 
in vertical sync interval units. 





Vsync() may generate a timeout if long blocking periods are specified. To prevent deadlocks, rather than 
using Vsync() to block for an especially long time (say more than 4 vertical blank periods), have your 
program poll VSync(-1) in a loop instead. 





Return value 
Mode value is as listed below. 











Table 7-11 
Mode Return value 
mode>=0 Time elapsed from the point that Vsync() 
processing is last completed when 
mode=0 or n (horizontal blanking units) 
mode<O Time elapsed after program boot (vertical 
blanking units) 
See also 


DrawSync(), VSyncCallback() 
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7-118 Basic Graphics Library Functions 


VSyncCallback 

Define a function to be executed during each vertical blank period. 
Library Header File Introduced Documentation Date 
libetc.lib libetc.h 2.X 12/14/98 

Syntax 

void VSyncCallback( 

void (*func)()) Pointer to callback function 

Explanation 


Specifies that the routine at address func should be executed at the start of the vertical blank interrupt. If 
func is O, then any previous callback routine is disabled. 


Subsequent interrupts are masked inside func. Therefore, it is necessary to return quickly after performing 
necessary processes using func. 


Although the specified function is called during an interrupt, it is not the actual interrupt handler. It should 
be written as a normal subroutine that are called by the main interrupt handler. 


See also 
VSync(), DrawSyncCallback() 
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Basic Graphics Library Macros 7-119 


Macros 





addVector 
Add vectors. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 
addVector(v0, v7) 


Arguments 
vO, v1 Pointers to vectors 


Explanation 
Adds v7 to the vector vO, and stores the result in vO. 


Since it is a macro, there is no dependence on the vector type. 


See also 
applyVector(), copyVector() 
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7-120 Basic Graphics Library Macros 


applyVector 

Apply arithmetic operation to a vector. 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 3.4 12/14/98 

Syntax 

applyVector(*v, x, y, Z, op) 

Arguments 

V Pointer to vector 

XYZ Coordinate value 

op Operator 

Explanation 


Performing the operation specified on vector v, x, y, Z and op 
applyVector (v, 2, 4, 8, +=) 


is equivalent to: 














v->vx += 2, v-> vxt= 4, v-> vx += 8 


applyVector is a macro, so there is no dependence on the vector model. 





See also 
addVector(), copyVector() 
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Basic Graphics Library Macros 7-121 


copyVector 
Copy vectors. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 


Syntax 
copyVector(v0, v7) 


Arguments 
vO, v1 Vector pointer 


Explanation 
Copies vector v7 to vO. 


copyVector is a macro, so there is no dependence on the vector type. 


See also 
addVector(), applyVector() 
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7-122 Basic Graphics Library Macros 


dumpMatrix 
Display matrix contents. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 


Syntax 
dumpMatrix(x) 
Arguments 


X pointer to matrix 


Explanation 


Displays the contents of the matrix pointed to by x. 
If SetDumpFnt() is called, the output is displayed to the screen. Otherwise, the output is sent to stdout. 





See also 
SetDumpFnt(), dumpRECT(), dumpVector(), dump...() 
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Basic Graphics Library Macros 7-123 


dumpRECT 

Display contents of a rectangle. 
Library Header File Introduced Documentation Date 
libgpu.tib libgpu.h 4.3 12/14/98 

Syntax 

dumpRECT() 

Arguments 

r pointer to RECT 

Explanation 


Displays the contents of the RECT structure pointed to by r. 
If SetDumpF nti) is called, the output is displayed to the screen. Otherwise, the output is sent to stdout. 





Since this is a macro, it does not depend on the vector type. 


See also 
SetDumpFnit(), dumpMatrix(), dumpVector(), dump. ..() 
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7-124 Basic Graphics Library Macros 


dumpVector 
Display contents of vector 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 


Syntax 
dumpVector(str, v) 


Arguments 

str string to be displayed 
v pointer to vector 
Explanation 


This macro displays the contents of the vector pointed to by v. 
If SetDumpFnt() is called, the output is displayed to the screen. Otherwise, the output is sent to stdout. 


See also 
SetDumpFnt(), dumpRECT(), dumpVector(), dump...() 
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dump... 


Basic Graphics Library Macros 


Display contents of a primitive. 


Library 
libgpu. lib 


Syntax 


dumpWH(p) 
dumpXYQ0(p) 
dumpXY2(p) 
dumpXY3(p) 
dumpXY4(p) 
dumpUVO(p) 
dumpUV3(p) 
dumpUV3() 
dumpRGBO(p) 
dumpRGB1(p) 
dumpRGB2(p) 
dumpRGB3\(p) 


Explanation 


Header File Introduced Documentation Date 


libgpu.h 4.3 12/14/98 


Displays w, h of primitive. 

Displays xO, yO of primitive. 

Displays xO, x1, yO, y1 of primitive. 
Displays x0-x2, yO-y2 of primitive. 
Displays x0-x3, yO-y3 of primitive. 
Displays uO, vO of primitive. 

Displays uO-u2, vO-v2 of primitive. 
Displays u0-u3, vO-v3 of primitive. 
Displays rO, gO, bO of primitive. 

Displays rO, r1, gO, g1, bO, b1 of primitive. 
Displays rO-r2, gO-g2, bO-b2 of primitive. 
Displays rO-r3, gO-g3, bO-b3 of primitive. 


Displays the contents of the primitive pointed to by p. If SetDumpFnt() is called, the output is displayed to 
the screen. Otherwise, the output is sent to stdout. 


Since these are macros, they do not depend on the primitive type. 


See also 
SetDumpFnit() 
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7-125 


7-126 Basic Graphics Library Macros 


setClut 
Set CLUT for primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 


Syntax 
setClut(p, x, y) 


Arguments 


p pointer to primitive 
X, y CLUT frame buffer address 


Explanation 

The texture CLUT ID specified by the parameters is set in the clut member of primitive p. 
Since this is a macro, it does not depend on the primitive type. 

For the CLUT address, the x component must be a multiple of 16. 


See also 
DumpClut(), GetClut(), LoadClut() 
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Basic Graphics Library Macros 7-127 


setRECT 

Set rectangular area. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

setRECT(r, x, y, w, h) 

Arguments 

r Pointer to RECT structure 

X, y Upper left point of rectangular area 

w, h Size of rectangular area 

Explanation 


This macro sets the x, y, w, and h values of the RECT structure r. 


See also 
dumpRECT\() 
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7-128 Basic Graphics Library Macros 


setRGBO, setRGB1, setRGB2, setRGB3 


Initialize RGB fields of a primitive. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 
Syntax 


setRGBO(p, rO, gO, bO) Initialize rO, gO, and bO fields 
setRGB1(p, r1, g1, b1) Initialize r1, g1, and b1 fields 
setRGB2(p, r2, 92, b2) Initialize r2, 92, and b2 fields 
setRGB3(p, r3, g3, b3) Initialize r3, g3, and b3 fields 


Arguments 

p Pointer to primitive 

r, 9g, b RGB members of primitive 
Explanation 





These macros set the values for the RGB members of the primitive p. 


These are macros, so there is no dependence on the primitive type. 
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Basic Graphics Library Macros 7-129 


setTPage 
Set texture page for primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 
Syntax 
setTPage(p, tp, abr, x, y) 
Arguments 
p pointer to primitive 
tp texture mode 
0: 4bitCLUT 
1: 8bitCLUT 
2:16bitDlrect 
abr semi-transparency rate 
0: 0.5 x Back + 0.5 x Forward 
1: 1.0 x Back + 1.0 x Forward 
2: 1.0 x Back - 1.0 x Forward 
3: 1.0 x Back + 0.25 x Forward 
X, y texture page address 
Explanation 


The texture page specified by the parameters is set in the toage member of primitive p. 


Since this is a macro, it does not depend on the primitive type. 


See also 
GetTPage(), SetDrawTPage(), LoadTPage() 
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7-130 Basic Graphics Library Macros 


setUVO, setUV3, setUV4 


Set the u and v members of a primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

setUVO0(*p, u0, vO) Set u0 and vO 

setUV3(*p, UO, vO, u1, v1, u2, v2) Set u0-u2 and v0-v2 

setUV4(*p, u0, vO, u1, v1, u2, v2, u3, v3) Set u0-u3 and vO-v3 

Arguments 

p Pointer to primitive 

u,v UV members of primitive 

Explanation 


These macros set the values of the appropriate UV fields of the primitive p. 


These are C preprocessor macros and can be used with any primitive or structure with the appropriate 
fields. 





See also 
setUVWH() 
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setUVWH 

Set the u, v members of a primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

setUVWH(‘p, u0, vO, w, h) 

Arguments 

p Pointer to primitive 

u0, vO Upper left corner of primitive texture 

w, h Width and height of primitive texture 

Explanation 





This macro sets the uO, vO, u1, v1, u2, v2, u3, and v3 fields of a primitive structure to represent the corners 
of the rectangle specified by the input parameters. 


It can be used with any primitive or structure with the appropriate fields; it cannot be used with sprite 
primitives. 


See also 
setUVO() 
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setVector 
Set the values of a vector. 


Library Header File Introduced Documentation Date 
libgpu.lib libgpu.h 2.X 12/14/98 


Syntax 
setVector("*v, x, y, Z) 


Arguments 


v Pointer to a vector 
X, Y, Z Coordinate values 


Explanation 
Sets the (x, y, Z) values of a VECTOR or SVECTOR (defined in libgte). 
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setWH 

Set the w,h members of a primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 

Syntax 

setWH("p, w, h) 

Arguments 

p Pointer to primitive. 

w, h Width and height of primitive texture 

Explanation 


Specifies the w,h members of a primitive (cannot be used with primitives which do not have w,h members). 


See also 
setXYWH() 
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setXY0, setXY2, setXY3, setXY4 


Set the x and y parameters of a primitive. 


Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 2.X 12/14/98 
Syntax 


setXY0(*p, xO, yO) 

setXY2(*p, xO, yO, x7, y1) 

setXY3(*p, x0, yO, x1, y1, x2, y2) 
setXY4(*o, xO, yO, x7, y1, x2, y2, x3, y3) 


Arguments 

p Pointer to primitive 

X,Y x, ymembers of primitive 
Explanation 


These macros set the values for the x, y members of the primitive. Because they are macros, there is no 
dependence on the primitive type. 





See also 
setXYWH() 
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setXYWH 

Set x, y members of a rectangular primitive. 
Library Header File Introduced Documentation Date 
libgpu. lib libgpu.h 4.3 12/14/98 

Syntax 

setXYWH(p, xO, yO, w, h) 

Arguments 

p pointer to primitive 

xO, yO upper left point of primitive 

w, h width and height of primitive 

Explanation 


The coordinates of the rectangle defined by (xO, yO)-(xO + w, yO + h) are set in members (xO, yO)..(x3, y3) of 
the primitive. This macro works with any primitive having (x0,y0)..(x3, y3) members. 


See also 
setXY0(), setWH() 


Run-Time Library Reference 


Chapter 8: Basic Geometry Library 
Table of Contents 





Structures 
CRVECTORS 8-5 
CRVECTOR4 8-6 
CVECTOR 8-7 
DIVPOLYGONS 8-8 
DIVPOLYGON4 8-9 
DVECTOR 8-10 
EVECTOR 8-11 
MATRIX 8-12 
POL3 8-13 
POL4 8-14 
QMESH 8-15 
RVECTOR 8-16 
SPOL 8-17 
SVECTOR 8-18 
TMESH 8-19 
VECTOR 8-20 
Functions 
ApplyMatrix 8-21 
ApplyMatrixLV 8-22 
ApplyMatrixSV 8-23 
ApplyRotMatrix 8-24 
ApplyRotMatrixLV 8-25 
ApplyTransposeMatrixLV 8-26 
AverageZ3 8-27 
AverageZ4 8-28 
catan 8-29 
CCOS 8-30 
Clip3F, Clip3FP, Clip3FT, Clipo3FTP, Clip3G, Clio3GT, Clip8GTP 8-31 
Clip4F, Clio4FP, Clip4FT, Clip4FTP, Clip4G, Clip4GT, Clip4GTP 8-33 
cln 8-35 
ColorCol 8-36 
ColorDpq 8-37 
ColorMatCol 8-38 
ColorMatDpq 8-39 
CompMatrix 8-40 
CompMatrixLV 8-41 
csin 8-42 
csqrt 8-43 
DivideF8, DivideF4, DivideFTS, DivideFT4, DivideG8, DivideG4, DivideGTS, DivideGT4 8-44 
DpqColor 8-46 
DpqColor3 8-47 
DpqColorLight 8-48 
EigenMatrix 8-49 
gteM|Mefunc 8-50 
InitClip 8-51 
InitGeom 8-52 
Intpl 8-53 
InvSquareRoot 8-54 
IsldMatrix 8-55 
LightColor 8-56 
LoadAverageO 8-57 
LoadAverage1 2 8-58 
LoadAverageByte 8-59 


CONFIDENTIAL Run-Time Library Reference 


Run-Time Library Reference 


LoadAverageCol 

LoadAverageShortO 
LoadAverageShort1 2 

LocalLight 

Lzc 

MatrixNormal 

MatrixNormal_O 

MatrixNormal_1 

MatrixNormal_2 

MulMatrix 

MulMatrixO 

MulMatrix2 

MulRotMatrix 

MulRotMatrixO 

NormalClip 

NormalColor, NormalColor_nom 
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NormalColorCol3, NormalColorCol3_nom 
NormalColorDpq, NormalColorDpq_nom 
NormalColorDpq3, NormalColorDpq3_nom 
otz2p 
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pers_map 

PhongLine 

PopMatrix 

PushMatrix 

ratan2 
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ReadGeomOffset 

ReadGeomScreen 
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RotMatrix_gte 
RotMatrixC 
RotMatrixx 
RotMatrixY 
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SubPol4 
TransMatrix 
TransposeMatrix 
TransRotPers 
TransRotPerss3 
TransRot_32 
VectorNormal 
VectorNormalS 
VectorNormalSS 
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CRVECTORS3 
Triangular recursive vector data. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Structure 
typedef struct { 


RVECTOR r01, r12, r20; Division vertex vector data 

RVECTOR “r0, *r7, *r2; Pointer to division vector data 

u_long *rtn; Pointer to return address for assembler 
} CRVECTOR3; 


See also 
RCpolyF3() 
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CRVECTOR4 


Quadrilateral recursive vector data. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Structure 


typedef struct { 
RVECTOR r01, r02, r31, r32, rc; Division vertex vector data 
RVECTOR “*r0, *r1, *r2, *r3; Pointer to division vertex vector data 
u_long “rtn; Pointer to return address for assembler 
} CRVECTOR4; 


See also 
RCpolyF4() 
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CVECTOR 
Character vector. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Structure 
typedef struct { 
u_char Fr, g, b; Color palette 
u_char cd; GPU code 
i 
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DIVPOLYGONS3 
Triangular division buffer. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Structure 
typedef struct { 
u_long ndiv; Number of divisions 
u_long pih, piv; Clip area specification (display screen resolution) 
u_short clut; CLUT 
u_short tpage; Texture page 
CVECTOR rgbc; Code + RGB color 
u_long “ot; Pointer to OT 


RVECTOR O, r1, r2; Division vertex vector data 
CRVECTORS cr/5]; Triangular recursive vector data 
} DIVPOLYGONS; 


See also 
DivideF3(), RCpolyF8() 
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DIVPOLYGON4 
Quadrilateral recursive vector data. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Structure 
typedef struct { 
u_long ndiv; Number of divisions 
u_long pih, piv; Clip area specification (display screen's resolution) 
u_short clut; CLUT 
u_short tpage; Texture page 
CVECTOR rgbc; Code + RGB color 
u_long “ot; Pointer to OT 
RVECTOR rO, r1, r2, r3; Division vertex vector data 
CRVECTOR4 crf5]; Quadrilateral recursive vector data 
} DIVPOLYGON4; 
See also 


DivideF4(), RCpolyF4() 
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DVECTOR 


2D vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 


Structure 


typedef struct { 
short vx, vy; Vector coordinates 
} DVECTOR; 


See also 
RotMeshH(), RotTransPers3N(), RotTransPersN() 
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EVECTOR 
Clip vector data. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Structure 
typedef struct { 
SVECTOR v; Local object 3D vertex 
VECTOR sxyz; Screen 3D vertex 
DVECTOR sxy; Screen 2D vertex 
CVECTOR rgb; Color palette 
short txuv, pad; Texture mapping data 
long chx, chy; Clip area data 
} EVECTOR; 
See also 


Clip3F(), Clip4FQ, InitClip( 
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MATRIX 


Matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Structure 
struct MATRIX { 
short m/3//3]; 3 x 3 matrix coefficient value 
long ¢/3]; Parallel transfer volume 
Explanation 
Specifies each component on the MATRIX m[Ii][j]. Specifies the transfer volume after conversion on the 
MATRIX t [I]. Pay attention to the differing word lengths on m and t. 





The GTE essentially performs the following multiply and accumulate calculations from the MATRIX 
structure. 


1. RotTrans system function (function group which does not perform coordinate conversion). Performs 
only basic matrix calculations and vector addition. 


MATRIX m 
SVECTOR xi 
SVECTOR xo 
Ixo.vx | [m.m[O}[O] m.m] m.mjol | F xi.vx | fmt 1] 
[xo.vy | =| m.m[A][O] m.m[t][1] mmp l | xivy bl mt] | 
[xoz] Lm.m[2][0] m.m[2][4] m.m[2][2] | Lxivz] Lmt ] 


2. RotTransPers system function (function group which performs coordinate conversion). In addition to 
the (a) calculation, perspective conversion (division by z) is performed at the same time. 





MATRIX m 
SVECTOR xi 
SVECTOR xO 
SVECTOR x2 
long h 
[xo.vx | [m.m[O][0] m.m[0][1] m.m[o][2] 1 T xi-vx | [m.to] | 
lxo.vy |= [m.m] m.m] m.m | | xivy l+ [m] | 
Lxo.vz | Lm.m[2][0] m.m[2][1] m.m[2][2] | L xi.vz J [mta] J 


X2.VX = (N*xO.Vvx) / XO.VZ 


x2.vy = (h*yo.vy) / xO.vz 
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POL3 
Triangle polygon. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Structure 
struct POLS { 
short sxy/3]/2]; Screen coordinates 
short sz/3]/2/; Screen coordinates 
short uv/3]/2]; Texture coordinates 
short rgb/3]/[3]; RGB value 
short code; Code (F3 = 1, FT3 = 2, G3 = 3, GT3 = 4) 
} 
See also 
SubPol3() 
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POL4 
Four-sided polygon. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Structure 
struct POL4 { 
short sxy/4]/2]; Screen coordinates 
short sz/4]/2/; Screen coordinates 
short uv/4)/2]; Texture coordinates 
short rgb/4][3]; RGB value 
short code; Code (F4 = 5, FT4 = 6, G4 = 7, GT4 = 8) 
} 
See also 
SubPol4() 
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QMESH 
Quadrilateral mesh 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.3 12/14/98 
Structure 
typedef struct { 
SVECTOR *v; pointer to shared vertex coordinates array 
SVECTOR “n; pointer to shared normal array 
SVECTOR *u; pointer to shared texture coordinates array 
CVECTOR “c; pointer to shared color data array 
u_long /env; vertex length (horizontal) 
u_long lenh; vertex length (vertical) 
JQMESH; 
See also 


RotMeshPrimQ_T() 
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RVECTOR 
Division vertex vector data. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Structure 
typedef struct { 
SVECTOR v; Local object 3D vertex 
u_char uv/2]; Texture mapping data 
u_short pad; 
CVECTOR c; Vertex color palette 
DVECTOR sxy; Screen 2D vertex 
u_long sz; Clip Z-data 
} RVECTOR; 
See also 


RCpolyF3(), RCpolyF4() 
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SPOL 
Vertex information. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Structure 
struct SPOL { 
short xy/3/; XY coordinates 
short uv/2]; UV coordinates 
short rgb/3]; RGB value 
See also 


SubPol38(), SubPol4() 
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SVECTOR 
Short vector. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Structure 
struct SVECTOR { 
short vx, vy, vz; Vector coordinates 
short pad; System reserved 


} 
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TMESH 
Triangle mesh. 
Library Header File Introduced Documentation Date 
libgte. lib libgte.h 2.x 12/14/98 
Structure 
struct TMESH { 
SVECTOR *v; Pointer to vertex string 
SVECTOR “n; Pointer to normal string 
SVECTOR “u; Pointer to texture string 
CVECTOR “c; Pointer to RGB string 
u_long /en; Mesh length 
See also 


RotMeshPrimR...(), RotMeshPrimS...() 
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VECTOR 
Vector. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Structure 
struct VECTOR { 
long vx, vy, vZ; Vector coordinates 
long pad; System reserved 
} 
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ApplyMatrix 

Multiply a vector by a matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

VECTOR *ApplyMatrix( 

MATRIX *m, Pointer to matrix to be multiplied (input) 

SVECTOR *vo, Pointer to short vector (input) 

VECTOR *v7) Pointer to vector (output) 

Explanation 


Multiplies the matrix m by the short vector vO beginning with the rightmost end. The vector is in effect 
rotated and then translated. 


The result is saved in the vector v7. The function destroys the constant rotation matrix. 


m ->m [i] [j] : (1,3, 12) 
vO -> vX, Vy, VZ : (1, 15, 0) 
V1 -> VX, vy, VZ : (1, 31, 0) 
Return value 

vi. 

See also 


ApplyMatrixLv(), ApplyMatrixSV(), ApplyRotMatrix(), ApplyRotMatrixLV(), ApplyTransposeMatrixLV() 
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ApplyMatrixLV 

Multiply a vector by a matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

VECTOR *ApplyMatrixLV( 

MATRIX *m, Pointer to matrix to be multiplied (input) 

VECTOR *vO, Pointer to vector (input) 

VECTOR *v7) Pointer to vector (output) 

Explanation 


Multiplies matrix m by vector vO beginning from the rightmost end. The result is saved in vector v7. It isa 16 
x 82 bit multiplier which uses the GTE. It destroys the constant rotation matrix. 


m ->m [i] [i] : (1, 3, 12) 
vO -> vX, Vy, VZ : (1, 31, 0) 
v{ -> VX, vy, VZ : (1, 31, 0) 
Return value 

vi 

See also 


ApplyMatrix(), ApplyMatrixSV(), ApplyRotMatrix(), ApplyRotMatrixLV(), AoplyTransposeMatrixLV() 
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ApplyMatrixSV 

Multiply a vector by a matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

SVECTOR *ApplyMatrixSV( 

MATRIX *m, Pointer to matrix to be multiplied (input) 

SVECTOR “vO, Pointer to short vector (input) 

SVECTOR *v1) Pointer to short vector (output) 

Explanation 





Multiplies matrix m by short vector vO beginning at the rightmost end. The result is saved in the short vector 
v1. This function destroys the rotation matrix. 


m ->m [i] [i] : (1, 3, 12) 
vO -> vX, Vy, VZ : (1, 15, 0) 
v{ -> VX, vy, VZ : (1, 15, 0) 
Return value 

vi 

See also 


ApplyMatrix(), AoplyMatrixLV(), ApplyRotMatrix(), ApplyRotMatrixLV(), ApplyTransposeMatrixLV() 
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ApplyRotMatrix 
Multiply a vector by a constant rotation matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

VECTOR *ApplyRotMatrix( 

SVECTOR “vO, Pointer to short vector (input) 

VECTOR *v1) Pointer to vector (output) 

Explanation 

Multiplies a constant rotation matrix by short vector vO beginning at the rightmost end. The result is saved 

in vector v1. 


VO -> Vx, Vy, VZ : (1, 15, 0) 
V1 -> VX, VY, VZ : (1, 31, 0) 


Return value 
v1 


See also 
ApplyMatrix(), ApplyMatrixLV(), ApplyMatrixSV(), ApplyRotMatrixLV(), ApplyTransposeMatrixLV() 
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ApplyRotMatrixLV 

Multiply a vector by a constant rotation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

VECTOR *ApplyRotMatrixLV( 

VECTOR *vO, Pointer to long vector (input) 

VECTOR *v1) Pointer to vector (output) 

Explanation 


Multiplies a constant rotation matrix by long vector vO beginning at the rightmost end. The result is saved in 
vector v7. 


VO -> VX, VY, VZ : (1, 31, O) 
v1 -> VX, VY, VZ : (1, 31, 0) 
Return value 

v1 

See also 


ApplyMatrix(), ApplyMatrixLV(, ApplyMatrixSV(), ApplyRotMatrix(), ApplyTransposeMatrixLV() 
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ApplyTransposeMatrixLV 


Multiply a vector by a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.2 12/14/98 

Syntax 

VECTOR *ApplyTransposeMatrixLV( 

MATRIX *m, Pointer to matrix to be multiplied 

VECTOR *vO, Pointer to vector (input) 

VECTOR *v1) Pointer to vector (output) 

Explanation 

Multiplies a transposed matrix by vector vO beginning at the rightmost end. The result is saved in vector v1. 

m ->m [i] fi] : (1,3, 12) 

vO -> VX, VY, VZ : (1,31, 0) 

v1 -> VX, VY, VZ : (1, 31, 0) 

Return value 

vi 

See also 


ApplyMatrix(), ApplyMatrixLV(), ApplyMatrixSV(), ApplyRotMatrix(), ApplyRotMatrixLv() 
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AverageZ3 

Average three values. 
Library Header File Introduced Documentation Date 
libgte. lib libgte.h 3.0 12/14/98 

Syntax 


long AverageZ3( 
long sz0, long sz7, long sz2) Input values 





Explanation 

Calculates an average of three values szO, sz7, and sz2. 
SZO, SZ1, SZ2 : (O, 16, 0) 

Return value : (O, 16, 0) 


Return value 
Average of 1/4 of three values szỌ, sz7, and sz2. 


See also 
AverageZA4\() 
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AverageZ4 

Average four values. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

long AverageZ4( 

long sz0, long sz7, long sz2, long sz3) Input values 

Explanation 

Calculates an average of four values szO, sz7, sz2, and sz3. 

SZO, SZ1, SZ2, SZ3 : (O, 16, 0) 

Return value : (O, 16, 0) 


Return value 
1/4 of the average of four values szO, sz7, sz2, and sz3. 


See also 
AverageZ3() 
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catan 

Compute arctangent of an angle within 180 degrees. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

int catan( 

int a) Value 

Explanation 


Uses PlayStation® format (where 4096 = 360 degrees = 2pai) to find the arctan (between -90 and +90 
degrees, -pai/2...pai/2) of a. 


a: (1, 19, 12) 


Return value 
atan (a): (1, 19, 12) 


See also 
ratan2(), ccos(), csin() 
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ccos 

Compute cosine of an angle. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

int ccos( 

int a) Angle (in PlayStation format) 

Explanation 


Finds the cosine function of the angle (in PlayStation format) (4096 = 360 degrees = 2 pai) using fixed point 
math (where 4096 = 1.0). 


Compared to rcos(), ccos() is slower and takes up less space 
a : PlayStation format (4096 = 360 degrees = 2pai) 


Return value 
cos (a) : (1, 19, 12) 


See also 
rcos(), csin(), catan() 
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Clip3F, ClipSFP, ClipSFT, Clip3FTP, Clip3G, Clip3GT, Clip3GTP 


Three-vertex clipping functions. 


Syntax 


Flat-shaded, no perspective transformation. 
long Clip3F(SVECTOR “vO, SVECTOR “v7, SVECTOR *v2, EVECTOR **evmx) 


Flat-shaded,with perspective transformation 
long Clip3FP(SVECTOR *v0O, SVECTOR *v7, SVECTOR *v2, EVECTOR **evmx) 


Flat-shaded, textured, no perspective transformation 
long Clip3FT(SVECTOR *vO, SVECTOR “v7, SVECTOR *v2, short “uv0, short *uv7, short *uv2, 
EVECTOR **evmx) 


Flat-shaded, textured, with perspective transformation 
long Clip3FTP(SVECTOR *v0O, SVECTOR *v7, SVECTOR *v2, short *uvO, short *uv7, short *uv2, 
EVECTOR **evmx) 


Gouraud-shaded, no perspective transformation 
long Clip3G(SVECTOR “vO, SVECTOR *v7, SVECTOR *v2, CVECTOR *rgb0, CVECTOR *rgb1, 
CVECTOR *rgb2, EVECTOR **evmx) 


Gouraud-shaded, with perspective transformation 
long Clip3GP(SVECTOR “v0, SVECTOR *v7, SVECTOR “v2, CVECTOR *rgb0, CVECTOR *rgb1, 
CVECTOR *rgb2, EVECTOR **evmx) 


Gouraud-shaded, textured, no perspective transformation 
long Clip3GT(SVECTOR *v0O, SVECTOR *v7, SVECTOR *v2,short *uvO, short *uv7, short 
“uv2, CVECTOR “rgb0, CVECTOR *rgb1, CVECTOR *rgb2, EVECTOR **evmx; 





Gouraud-shaded, textured, with perspective transformation 
long Clip83GTP(SVECTOR *vO, SVECTOR *v7, SVECTOR *v2,short *uv0, short *uv7, short 
*uv2, CVECTOR “rgb0, CVECTOR *rgb1, CVECTOR *rgb2, EVECTOR **evmx; 


Explanation 
These functions clip a triangle having vertices vO, v7, and v2 to six surfaces defined by InitClip(). Other input 
parameters are: 


uv0, uv7, uv2: Pointers to texture coordinate vectors 
rgb0, rgb1, rgb2: Pointers to vertex color data 


Effective output clip vector data is stored in evmx. The following members of evmx are returned depending 
on the particular function: 


evmx[i] -> v Local Object 3D Vertex (all functions) 
evmx{i] -> sxyz Screen 3D Vertex (all functions) 

evmx{i] -> sxyz.pad Fog effect interpolation value (P functions) 
evmx{i] -> sxy Screen 2D Vertex (P functions) 

evmx{i] -> rgb Vertex Color Data (G functions) 

evmx[i] -> txuv Texture Mapping Data (T functions) 
evmx[i] -> chx chx = vz * (nw/2)/h_ (all functions) 

evmxļi] -> chy chy = vz * (vw/2)/h (all functions) 





These functions reserve the pointer arrays (20 pointer arrays = 80 bytes), including the work area. 


Return value 
Output number of vertices. 
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See also 
Clip4F(), InitClip( 
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Clip4F, Clip4FP, Clip4FT, Clip4FTP, Clip4G, Clip4GT, Clip4GTP 
Four-vertex clipping functions. 


Syntax 


Flat-shaded, no perspective transformation. 
long Clip4F(SVECTOR *vO, SVECTOR “v7, SVECTOR *v2, SVECTOR “v3, EVECTOR**evmx) 


Flat-shaded,with perspective transformation 
long Clip4FP(SVECTOR *vO, SVECTOR *v7, SVECTOR “v2, SVECTOR “v3, EVECTOR *evmx) 


Flat-shaded, textured, no perspective transformation 
long Clip4FT(SVECTOR *vO, SVECTOR “v7, SVECTOR *v2, SVECTOR “v3, short *uvO, short *uv7, 
short *uv2, short *uv3, EVECTOR **evmx) 


Flat-shaded, textured, with perspective transformation 
long Clip4FTP(SVECTOR *vO, SVECTOR “v7, SVECTOR *v2, SVECTOR “v3, short *uv0, short “uv7, 
short *uv2, short *uv3, EVECTOR **evmx) 


Gouraud-shaded, no perspective transformation 
long Clip4G(SVECTOR “vO, SVECTOR *v7, SVECTOR “v2, SVECTOR *v3, CVECTOR “rgb0, CVECTOR 
*rgb1, CVECTOR *rgb2, EVECTOR **evmx) 


Gouraud-shaded, with perspective transformation 
long Clip4GP(SVECTOR “v0, SVECTOR *v7, SVECTOR “v2, SVECTOR *v3, CVECTOR “*rgbo, 
CVECTOR *rgb1, CVECTOR “rgb3, CVECTOR *rgb2, EVECTOR **evmx) 


Gouraud-shaded, textured, no perspective transformation 

long Clip4GT(SVECTOR *vO, SVECTOR *v7, SVECTOR “v2, SVECTOR “v3, short *uv0, short *uv7, 
short *uv2, short *uv3, CVECTOR *rgb0, CVECTOR *rgb7, CVECTOR *rgb2, CVECTOR *rgb3, 
EVECTOR **evmx; 


Gouraud-shaded, textured, with perspective transformation 

long Clip4GTP(SVECTOR *v0, SVECTOR *v7, SVECTOR “v2, SVECTOR *v3, short *uvO, short *uv7, 
short “uv2, short *uv3, CVECTOR *rgb0, CVECTOR *rgb1, CVECTOR *rgb2, CVECTOR “rgb3, 
EVECTOR **evmx; 





Explanation 
These functions clip a quadrilateral (linked triangle) having vertices vO, v7, v2, and v3 to six surfaces defined 
by InitClip(). Other input parameters are: 





uv0, uv7, uv2, uv3: Pointers to texture coordinate vectors 
rgb0, rgb1, rgb2, rgb3: Pointers to vertex color data 


Effective output clip vector data is stored in evmx. The following members of evmx are returned depending 
on the particular function: 


evmx[i] -> v Local Object 3D Vertex (all functions) 
evmx{i] -> sxyz Screen 3D Vertex (all functions) 

evmx{i] -> sxyz.pad Fog effect interpolation value (P functions) 
evmx{i] -> sxy Screen 2D Vertex (P functions) 

evmx{i] -> rgb Vertex Color Data (G functions) 

evmx[i] -> txuv Texture Mapping Data (T functions) 
evmx[i] -> chx chx = vz * (nw/2)/h (all functions) 

evmxļi] -> chy chy = vz * (vw/2)/h (all functions) 


These functions reserve the pointer arrays (20 pointer arrays = 80 bytes), including the work area. 


Return value 
Output number of vertices. 
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See also 
Clip3F(), InitClip() 
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cin 
C logarithm function. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 
int cln( 
int a) Value 


Explanation 
Uses fixed point math (where 4096 = 1.0) to find the fixed point natural logarithm. 


a: (1, 19, 12) 


Return value 
In (a): (1, 19, 12) 
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ColorCol 

Find a local color from a local light vector. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void ColorCol( 

VECTOR *vO, Pointer to local light vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

CVECTOR *v2) Pointer to color vector (output) 

Explanation 


Calculates the following: 
LC = BK + LCM * vO 


v2 = v1 * LC (product of multiplication) 


VO -> VX, VY, VZ : (1, 19, 12) 
v1 ->r,g,b :(0, 8, 0) 
v2 ->1r,g,b :(0, 8, 0) 
See also 


ColorDpq(), ColorMatCol(), ColorMatDpq() 
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ColorDpq 

Find a local color from a local light vector, and perform depth cueing. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void ColorDpq( 

VECTOR “vO, Pointer to local light vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

long p, Interpolation value for depth cueing (input) 

CVECTOR *v2) Pointer to color vector (output) 

Explanation 


Calculates the following: 
LC = BK + LCM x vO 
v2 = (1-p) xv7x LC +pxFC 


where v7 x LC is the product of separate multiplication. 


VO -> VX, VY, VZ : (1, 19, 12) 
vl ->r,g, b : (0, 8, O) 

p : (O, 20, 12) 
v2 ->r,g, b : (0, 8, O) 
See also 


ColorCol(), ColorMatCol(), ColorMatDpq() 
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ColorMatCol 

Find a color. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void ColorMatCol( 

SVECTOR “vO, Pointer to normal vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

CVECTOR *v2, Pointer to color vector (output) 

long matc) Material (output) 

Explanation 

Performs the following calculations: 

LLV = LLM * vO 


LLV = LLVA (2Amatc) 
LC = BK + LCM *LLV 


v2 = v1 * LC (separate multiplications) 


VO -> VX, VY, VZ : (1, 3, 12) 
v1 ->r,g,b : (0, 8, O) 
v2 ->1r,g,b : (0, 8, O) 
matc : (0, 32, 0) 
See also 


ColorCol(), ColorDpq(), ColorMatDpq() 
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ColorMatDpq 

Find a color and perform depth cueing. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void ColorMatDpq( 

SVECTOR “vO, Pointer to normal vector (input) 

CVECTOR *v1, Pointer to color vector (input) 

long p, Interpolation value for depth cueing (output) 

CVECTOR “v2, Pointer to color vector (output) 

long matc) Material (output) 

Explanation 

Performs the following calculations: 

LLV = LLM x vO 


LLV = LLV^ (2^matc) 
LC = BK + LCM x LLV 
v2 = (1-p)xv1 xLC + p x FC. 


VO -> VX, VY, VZ : (1,3, 12) 
v1 ->r, g, b : (0, 8, O) 

p : (O, 20, 12) 
v2 ->r,g, b : (0, 8, O) 
matc : (0, 32, 0) 
See also 


ColorCol(), ColorDpq(), ColorMatCol() 
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CompMatrix 

Make a composite coordinate transformation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

MATRIX *CompMatrix( 

MATRIX *m0, MATRIX *m1, — Pointer to matrix (input) 

MATRIX *m2) Pointer to matrix (output) 

Explanation 


Makes a composite coordinate transformation matrix that includes parallel translation. 
[m2 -> m] = [mO -> m] * [m1 -> m] 


(m2 -> t) = [mO -> m] * (m1 -> t) + (mO -> t) 





However, the values of the elements of m1 -> t should be in the range (-2415, 2415). 


mO ->m [i] [i] (13,12 
mO ->t [i] (1, 31, 0) 
m1 ->m [i] [i] (1,3, 12) 
m1 ->t [i] : (1, 15, 0) 
m2 ->m [i] [i] (1, 3, 12) 
m2 ->t [i] (1, 31, 0) 


This function destroys a constant rotation matrix. 


Return value 
m2 


See also 
CompMatrixLV() 
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CompMatrixLV 

Make a composite coordinate transformation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.6 12/14/98 

Syntax 

MATRIX *CompMatrix( 

MATRIX *m0, MATRIX *m7, Pointer to matrix (input) 

MATRIX *m2) Pointer to matrix (output) 

Explanation 


Makes a composite coordinate transformation matrix that includes parallel translation. 


[m2->m] = [mO->m] * [m1->m] 
(m2->t) = [mO->m] * (m1->t) + (mO->t) 


mo -> m {il [j] (1, 3, 12) 
mo -> t [i] (1, 31, 0) 
m1 ->m [i] [j] : (1,3, 12) 
m1 ->t [i (1, 31, 0) 
m2 ->m [il [i (1, 3, 12) 
m2 ->t [i : (1, 31, 0) 


This function destroys a rotation matrix. 


Return value 
m2 


See also 
CompMatrix() 
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csin 
C sine function. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 


Syntax 
int csin( 
int a) Angle (in PlayStation format) 


Explanation 


Find the sine function of the angle (in PlayStation format) (4096 = 360 degrees = 2pai) using fixed point 
math (where 4096 = 1.0). 


Compared to rsin(), csin( is slower and takes up less space. 
a : PlayStation format (4096 = 360 degrees = 2pai) 


Return value 
sin (a) : (1, 19, 12) 


See also 
rsin), ccos(), catan() 
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csaqrt 
C square root function. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 
int csqrt( 
int a) Value 


Explanation 
Uses fixed point math (where 4096 = 1.0) to find the fixed point square root. 


This function is the same as SquareRoot12() except that it requires a smaller table memory area. 
a:(1, 19, 12) 

Return value 

sart (a) : (1, 19, 12) 


See also 
SquareRoot0(), SquareRoot1 2(), InvSquareRoot() 
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DivideF3, DivideF4, DivideFT3, DivideFT4, DivideG3, DivideG4, 
DivideGT3, DivideGT4 


Polygon division functions. 


Library Header File Introduced Documentation Date 
libgte.lib lipgte.h 3.0 12/14/98 

Syntax 

Flat triangle. 


u_long *DivideF3(SVECTOR “vO, SVECTOR “v7, SVECTOR “v2, CVECTOR “rgbc, POLY_F3 *s, u_long 
‘ot, DIVPOLYGONS “divp) 


Flat quadrilateral. 
u_long *DivideF4( SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR “v3, CVECTOR *rgbc, 
POLY_F4 *s, u_long “ot, DIVPOLYGON4 “divp) 


Flat textured triangle. 
u_long *DivideFT3( SVECTOR *vO, SVECTOR “v7, SVECTOR *v2, u_long *uv0, u_long *uv7, u_long 
*uv2, CVECTOR “rgbc, POLY_FT3 *s, u_long *ot, DIVPOLYGONS *divp) 


Flat textured quadrilateral. 
u_long *DivideFT4( SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR “v3, u_long “uv0, u_long 
*“uv1, u_long *uv2, u_long *uv3, CVECTOR “rgbc, POLY_FT4 *s, u_long “ot, DIVPOLYGON4 “divp) 


Gouraud-shaded triangle. 
u_long *DivideG3( SVECTOR “vO, SVECTOR “v7, SVECTOR *v2, CVECTOR “rgb0, CVECTOR *rgb1, 
CVECTOR *rgb2, POLY_G3 *s, u_long “ot, DIVPOLYGONS *divp) 


Gouraud-shaded quadrilateral. 
u_long *DivideG4( SVECTOR “vO, SVECTOR *v7, SVECTOR *v2, SVECTOR “v3, CVECTOR *rgb0, 
CVECTOR *rgb1, CVECTOR “rgb2, CVECTOR *rgb3, POLY_G4 *s, u_long *ot, DIVPOLYGON4 “divp) 


Gouraud-shaded, textured triangle. 

u_long *DivideGT3( SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, u_long *uvO, u_long *uv7, u_long 
*uv2, CVECTOR “rgb0, CVECTOR *rgb1, CVECTOR *rgb2, POLY_GT3 *s, u_long “ot, DIVPOLYGONS3 
“divp) 


Gouraud-shaded textured quadrilateral. 

u_long *DivideGT4( SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR *v3, u_long *uvO, u_long 
*uv1, u_long *uv2, u_long *uv3, CVECTOR “rgb0, CVECTOR *rgb7, CVECTOR *rgb2, CVECTOR *rgb3, 
POLY_GT4 *s, u_long *ot, DIVPOLYGON4 “divp) 


Explanation 
Divides a polygon and registers the result to the OT. 


vO — v3 are pointers to the vertex coordinate vectors. 





uvO — uv3, for textured polygons, are pointers to the texture coordinate vectors. 
rgbc is a pointer to a color vector + code. 

s is a pointer to the GPU packet buffer address. It depends on the polygon type. 
ot is a pointer to the OT entry 


divp is a pointer to the division work area. You must set divo->ndiv to the desired number of divisions, and 
divp->pih, divp->piv to the display screen (clipping) resolution. 


The divp -> ndiv values and division format are shown below: 
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Table 8-1: Division types 


divp->ndiv Number of divisions 
2x2 

4x4 

8x8 

16x 16 

32 x 32 








OhRWN 





rgb0O — rgb3, for Gouraud-sh 


aded polygons, are pointers to color vectors. 
rgb0:rgb0+code 


Return value 
Updated GPU packet buffer address. 
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DpqColor 

Interpolate a primary color vector and far color. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void DpqColor( 

CVECTOR “V0, Pointer to primary color vector (input) 

long p, Interpolation value (input) 

CVECTOR *v7) Pointer to primary color vector (output) 

Explanation 

Calculates v7 = (1-0) x vO + p x FC. 

vO ->r, g, b : (0, 8, O) 

p : (O, 20, 12) 

vi ->r,g, b : (0, 8, O) 

See also 


DpqColor3(, DeqColorLight() 
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DpqColor3 

Interpolate three primary color vectors and far color. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 


void DpqColor3( 
CVECTOR *v0O, CVECTOR *v7, CVECTOR *v2, Pointer to primary color vectors (input) 


long p, Interpolation value (input) 
CVECTOR *v3, CVECTOR “v4, CVECTOR *v5) Pointer to color vectors (output) 
Explanation 

Calculates: 


v3 = (1-p) x V0+ po x FC 
v4 = (1-p)xv1+pxFC 
V5 = (1-p) x v2 + p x FC. 


vO, v1, v2 ->r,g, b : (0, 8, O) 

p : (O, 20, 12) 
v3, v4, v5 ->r, g, b : (0, 8, O) 
See also 


DpqColor(), DeqColorLight() 
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DpqColorLight 

Interpolate the product from multiplication of a local color vector by primary color vector, and far color. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void DpqColorLight( 

SVECTOR *Vv0, Pointer to local color vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

long p, Interpolation value (input) 

CVECTOR *v2) Pointer to color vector (output) 

Explanation 


Calculates v2 = (1-p) x (v1 x v0) + p x FC. 


where v7 x vO is a separate multiplication product. 


vO -> VX, VY, VZ : (1,3, 12) 
v1 ->r, g, bD : (0, 8, O) 

p : (O, 20, 12) 
v2 ->r,g, b : (0, 8, O) 
See also 


DpqColor(), DeqColor3() 
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EigenMatrix 
Obtain the eigen matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.1 12/14/98 


Syntax 

void EigenMatrix( 

MATRIX *m, Input: rotation matrix 

MATRIX *t) Output: eigen matrix 

Explanation 

The eigen matrix (ordered eigen vectors) corresponding to the input rotation matrix, m, is output to the 
matrix t. 


The operation performed is shown below. 


1 0 0 
kM [m]* k" =]0 cose) — sin(e) 
O —sin(®) cos(@) 


m ->m [I] [i] gee 12) 
t ->m [I] [i] : (1,3, 12) 
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gteMIMefunc 

Add a vertex data array to a differential data array multiplied by a coefficient. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void gteMIMefunc( 

SVECTOR “otp, Pointer to a vertex array 

SVECTOR “dfp, Pointer to a differential array 

long n, Number of vertex (differential) data 

long p) Weight (control) coefficient: (1, 19, 12) 

Explanation 


Executes calculation of multiple interpolations using vertex data array and difference data array. The 
argument format is as follows: 


p :(1, 19, 12) 
otp, dfp optional 


It operates at high speed in a similar way to the program given in the example below. 





void gteMIMefunc (otp, dfp, n, p) 
SVECTOR *otp, *dfp; 


long n, p; 

{ 

int- dis 

for (i = 0; i<n; i++) { 


(otp+i)->x+=( (int) ((dfpti)—->x) x p)>>12; 

(otpti)—>yt+=( (int) ((dfp+i)->y) x p)>>12; 

(otp+i)->z+=( (int) ((dfpti)->z) x p)>>12; 
} 
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InitClip 

Initialize clipping parameter. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

void InitClip( 

EVECTOR “evbfad, Pointer to 16 clip vector data arrays 

long hw, Window width 

long wy, Window height 

long h, Projection distance from view point to screen 

long near, NearClip position 

long far) FarClip position 

Explanation 


Sets parameters used for clipping. 


The clip vector data array evbfad reserves 16 data arrays (176 words or 704 bytes). 


See also 
Clip3F(), Clip4FQ) 


CONFIDENTIAL Run-Time Library Reference 


8-52 Basic Geometry Library Functions 


InitGeom 

Initialize the geometry transform engine. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void InitGeom(voic) 


Explanation 
Initializes the GTE. It must be called whenever the basic geometry library is used. 
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Intpl 

Interpolate a vector and far color. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void Intpl( 

SVECTOR “vO, Pointer to vector (input) 

long p, Interpolation value (input) 

CVECTOR *v1) Pointer to vector (output) 

Explanation 

Calculates v7 = (1-0) x vO + p x FC. 

VO -> VX, VY, VZ : (1,3, 12) 

p : (O, 20, 12) 

v1 ->r,g,b : (0, 8, O) 
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InvSquareRoot 

Inverse square root. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void InvSquareRoot( 

long a, Value 

long *b, Pointer to mantissa 

long *c) Pointer to exponent 

Explanation 

Calculates 1/square root of a. 

a : (0, 32, 0) 

b : (0, 20, 12) 

C : (0, 32, 0) 


If a > 0x7FFFFFF, a processor exception will occur. 


See also 
csqrt(), SquareRoot1 2() 
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IsidMatrix 

Judge distance from unit matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.1 12/14/98 

Syntax 

void IsldMatrix( 

MATRIX *m) Input matrix 

Explanation 


Compares the input matrix m with the unit matrix. If the elements of matrix m are less than 20 away from 
the unit matrix, the function returns the value 1. 


m ->m (i i : (1,3, 12) 


Return value 
1 if the matrix is the unit matrix, else O. 
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LightColor 
Coordinate transformation using the local color matrix. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 
Syntax 
void LightColor( 
SVECTOR “vO, Pointer to vector (input) 
VECTOR *v1) Pointer to vector (output) 
Explanation 
Calculates v1=LCM * vO. A limiter works on negative components of v7 when 0 is reached. 
VO -> VX, VY, VZ : (1,3, 12) 
V1 -> VX, W, VZ : (0, 20, 12) 
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LoadAverage0O 

Weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 

Syntax 


void LoadAverage0( 
VECTOR *v0, VECTOR *v7, Pointer to vectors (input) 


long pO, long p1, Weights (input) 

VECTOR “*v2) Pointer to vector (output) 

Explanation 

Returns the weighted average of two vectors vO and v7 in v2 using weights of p0 and p1. 
VO, v1 -> VX, VY, VZ : (1, 31, 0) 

po, p1 : (1, 15, 0) 

V2 -> VX, VY, VZ : (1, 31, O) 

See also 


LoadAverage1 2(), LoadAverageByte(), LoadAverageCol(), LoadAverageShort0(), LoadAverageShort1 2() 
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LoadAverage12 

Weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void LoadAverage12( 
VECTOR *v0, VECTOR *v1, Pointer to vectors (input) 


long pO, long p1, Weights (input) 
VECTOR *v2) Pointer to vector (output) 
Explanation 





Finds the weighted average of two vectors vO and v7 using weights of p0 and p1 after division by 4096 (1 
in fixed point format) the results are returned in v2. 


vO, v1 -> VX, Vy, VZ : (1, 31, 0) 
po, p1 > (1, 3, 12) 
V2 -> VX, VY, VZ : (1, 31, 0) 
See also 


LoadAverage0(), LoadAverageByte(), LoadAverageCol(), LoadAverageShort0(), LoadAverageShort1 2() 
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Basic Geometry Library Functions 8-59 


LoadAverageByte 

Find weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte. lib libgte.h 3.0 12/14/98 

Syntax 


void LoadAverageByte( 
u_char v0/2], u_char v7/2], Vector (input) 


long pO, p1, Weights (input) 
u_char v2/2) Vector (output) 
Explanation 





Finds the weighted average of two vectors vO and v7 using weights p0 and p1. The result is returned in v2 
after division by 4096. 


vOfi], v7 [i] : (0, 8, 0) 
pO, p1 : (1,3, 12) 
v2ļi] : (0, 8, O) 
See also 


LoadAverage0(), LoadAverage12(), LoadAverageCol(), LoadAverageShort0(), LoadAverageShort1 2() 
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8-60 Basic Geometry Library Functions 


LoadAverageCol 

Find weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

void LoadAverageCol( 

u_char vO/3], u_char v7/3], Vectors (input) 

long pO, long p1, Weights (input) 

u_char v2/3)) Vector (output) 

Explanation 





Finds the weighted average of two vectors vO and v7 using weights p0 and p1. The result is returned in v2 
after division by 4096. 


vOfi], v7 [i] : (0, 8, 0) 
pO, p1 : (1,3, 12) 
v2ļi] : (0, 8, 0) 
See also 


LoadAverage0(), LoadAverage12(), LoadAverageByte(), LoadAverageShortO(), LoadAverageShort120 
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Basic Geometry Library Functions 8-61 


LoadAverageShort0 

Weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void LoadAverageShort0( 

SVECTOR *vO, SVECTOR *v7, Pointer to vectors (input) 

long p0, long p1, Weights (input) 

SVECTOR *v2) Pointer to vector (output) 

Explanation 

Returns the weighted average of two vectors vO and v7 in v2 using weights of p0 and p1. 

VO, v1 -> VX, VY, VZ : (1, 15, 0) 

po, p1 : (1, 15, 0) 

V2 -> VX, VY, VZ : (1, 30, 0) 

See also 


LoadAverage0(), LoadAverage1 2(), LoadAverageByte(), LoadAverageCol(), LoadAverageShort1 2() 
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8-62 Basic Geometry Library Functions 


LoadAverageShort12 

Weighted average of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void LoadAverageShort12( 
SVECTOR *vO, SVECTOR *v7, Pointer to vectors (input) 


long pO, long p1, Weights (input) 
SVECTOR *v2) Pointer to vector (output) 
Explanation 





Finds the weighted average of two vectors vO and v7 using weights of p0 and p1 after division by 4096 (1 
in fixed point format) the results are returned to v2. 


vO, v1 -> VX, Vy, VZ : (1, 15, 0) 
pO, p1 :(1, 3, 12) 
V2 -> VX, VY, VZ : (1, 15, 0) 
See also 


LoadAverage0(), LoadAverage 2(), LoadAverageByte(), LoadAverageCol(), LoadAverageShortO() 
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Basic Geometry Library Functions 8-63 


LocalLight 
Coordinate transformation using the local light matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Syntax 
void LocalLight( 
SVECTOR “vO, Pointer to vector (input) 
VECTOR *v1) Pointer to vector (output) 
Explanation 
Calculates v1=LLM*vO. A limiter works on negative components of v7 when 0 is reached. 
VO -> VX, VY, VZ: (1, 3, 12) 
V1 -> VX, Wy, VZ: (0, 20, 12) 
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8-64 Basic Geometry Library Functions 


Lzc 

Calculate leading zero count. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long Lzc( 

long data) Value 

Explanation 

Calculates the Leading Zero Count (LZC) given by data. 

data : (1, 31, 0) 


Return value 
The value of LZC. 
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Basic Geometry Library Functions 8-65 


MatrixNormal 


Normalize a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 


Syntax 

void MatrixNormal( 

MATRIX *m, Pointer to matrix (input) 
MATRIX *n) Pointer to matrix (output) 
Explanation 

Orthonormalizes a distorted rotation matrix. 


(Do not use m[2][0], m[2][1], m[2][2].) 


m ->m [i] [i]: (1, 3, 12) 
n ->m {i ij: (1, 3, 12) 
See also 


MatrixNormal_O(), MatrixNormal_1(), MatrixNormal_2() 
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8-66 Basic Geometry Library Functions 


MatrixNormal_0O 


Orthonormalize a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.6 12/14/98 

Syntax 

void MatrixNormal_0( 

MATRIX *m, Pointer to matrix (input) 

MATRIX *n) Pointer to matrix (output) 

Explanation 


Orthonormalizes a distorted rotation matrix. 
(Do not use m[2][O], m[2][1], m[2][2].) 


m ->m [i] [j]: (1, 3, 12) 
n ->m {i i: (1, 3, 12) 
See also 


MatrixNormal_1(), MatrixNormal_2() 


Run-Time Library Reference CONFIDENTIAL 


Basic Geometry Library Functions 8-67 


MatrixNormal_ 1 


Normalize a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 

Syntax 

void MatrixNormal_1( 

MATRIX *m, Pointer to matrix (input) 

MATRIX *n) Pointer to matrix (output) 

Explanation 


Orthonormalizes a distorted rotation matrix. 
(Do not use m[O][O], m[O][1], m[O][2].) 


m ->m [i] [i] (1,3, 12) 
n ->m [i] [i] (1, 3, 12) 
See also 


MatrixNormal_O(), MatrixNormal_2() 
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8-68 Basic Geometry Library Functions 


MatrixNormal_ 2 


Normalize a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 

Syntax 

void MatrixNormal_2( 

MATRIX *m, Pointer to matrix (input) 

MATRIX *n) Pointer to matrix (output) 

Explanation 


Orthonormalizes a distorted rotation matrix. 
(Do not use m[1][O], m[1][1], m[1][2].) 


m ->m [i] fj] : (1, 3, 12) 
n ->m [i] [i] : (1, 3, 12) 
See also 


MatrixNormal_O(), MatrixNormal_1() 
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Basic Geometry Library Functions 8-69 


Mul Matrix 

Multiply two matrices. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 


MATRIX *MulMatrix( 
MATRIX *m0, MATRIX *m7) Pointer to input/output matrices 


Explanation 
Multiplies two matrices. The result is saved in m0. 
m0,m1 ->m [i] [j] HALa 12) 


The function destroys the constant rotation matrix. 


Return value 
mo. 


See also 
MulMatrixO(), MulMatrix2(), MulRotMatrix(), MulRotMatrixO() 
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8-70 Basic Geometry Library Functions 


MulMatrixO 

Multiply two matrices. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 


MATRIX *MulMatrix0( 

MATRIX *m0, MATRIX *m7, Pointer to input matrices 
MATRIX *m2) Pointer to output matrix 
Explanation 

Multiplies two matrices mO and m7. 

m0,m1,m2->m {i j] : (1,3, 12) 

The function destroys the constant rotation matrix. 


Return value 
me. 


See also 
MulMatrix(), MulMatrix2(), MulRotMatrix(), MulRotMatrixO() 
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Basic Geometry Library Functions 8-71 


MulMatrix2 

Multiply two matrices. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 


MATRIX *MulMatrix2( 
MATRIX *m0, MATRIX *m7) Pointer to input/output matrices 


Explanation 
Multiplies two matrices. The result is saved in m7. 
m0, m1 ->m [i] [j] : (1, 3, 12) 


The function destroys the constant rotation matrix. 


Return value 
mi. 


See also 
MulMatrix(), MulMatrixO(), MulRotMatrix(), MulRotMatrixO() 
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8-72 Basic Geometry Library Functions 


MulRotMatrix 


Multiply a constant rotation matrix by a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 


MATRIX *MulRotMatrix( 
MATRIX *m0) Pointer to input/output matrix 


Explanation 
Multiplies a constant rotation matrix by a matrix. It stores the value in m0. 


m0, m1 ->m [i] [j] : (1,3, 12) 
Return value 


Returns m0. 


See also 
MulMatrix(), MulMatrixO(), MulMatrix2(), MulRotMatrixO() 
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Basic Geometry Library Functions 8-73 


MulRotMatrixO 


Multiply a constant rotation matrix by a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 


MATRIX *MulRotMatrix0( 
MATRIX *mO, Pointer to input matrix 
MATRIX *m1) Pointer to output matrix 


Explanation 
Multiplies a constant rotation matrix by matrix mO. The result is saved in m7. 


m0, m1 ->m [i] [j] : (1,3, 12) 
Return value 


Returns m1. 


See also 
MulMatrix(), MulMatrixO(), MulMatrix2(), MulRotMatrix() 
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8-74 Basic Geometry Library Functions 


NormalClip 

Outer product of three points. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long NormalClip( 

long sxy0, long sxy7, long sxy2) Input values (upper 16 bits are screen x coordinates (sx); lower 16 


bits are screen y coordinates (sy) 


Explanation 
Returns the outer product for a triangle formed by three points (sxO, sy0), (8x1, sy1), and (Sx2, sy2). 





When viewed from the direction of the viewpoint (Z axis negative) the value is positive when the triangle is 
righthanded. 


(However, the X axis positive faces right and the Y axis positive faces down.) 
sxyO, Sxy7, Sxy2 : (1, 15, 0), (1, 15, 0) 


Return value 
| sx1-sx0, sy1-sy0| 


| sx2-sx0, sy2-sy0| 


See also 
OuterProductO(), OuterProduct1 2() 
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Basic Geometry Library Functions 8-75 


NormalColor, NormalColor_nom 


Find a local color from a normal vector. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void NormalColor( 

SVECTOR “vO, Pointer to normal vector (input) 

CVECTOR *v7) Pointer to color vector (output) 


void NormalColor_nom( 


SVECTOR *v0) Pointer to normal vector (input) 
Explanation 

LLV = LLM * vO 

v1 = BK + LCM * LLV 

VO -> VX, VY, VZ : (1,3, 12) 

NormalColor(): v1-> r, g, b : (0, 8, 0) 


NormalColor_nom():The operation result(s) must be retrieved from the GTE. (For further information see the 
Inline Reference documentation.) 


e For (v1->r,v1->g, v1->b) use the read_rgb2 macro. 


See also 
NormalColor3(), NormalColorCol(), NormalColorCol3(), NormalColorDpq(), NormalColorDpq3() 
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8-76 Basic Geometry Library Functions 


NormalColor3, NormalColor3_nom 


Find three local colors from three normal vectors. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void NormalColor3( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to normal vectors (input) 


CVECTOR *v3, CVECTOR *v4, CVECTOR *v5) Pointer to color vectors (output) 


void NormalColor3_nom( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2) Pointer to normal vectors (input) 


Explanation 
(LLVO, LLV1, LLV2) = LLM * (vO, v1, v2) 


(v3, v4, v5) = BK + LCM * (LLVO, LLV1, LLV2) 
VO, v1, V2 -> VX, Vy, VZ : (1,3, 12) 


Norma!Color8(): v3, v4, v5 -> r, g, b : (0, 8, 0) 


NormalColor38_nom():The operation result(s) must be retrieved from the GTE (For further information, refer 
to the Inline Reference documentation): 





e For (v3,v4 and v5) use the read_rgb_fifo macro. 


See also 
NormalColor(), NormalColorCol(), NormalColorCol8(), NormalColorDpq(), NormalColorDpq3() 
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Basic Geometry Library Functions 8-77 


NormalColorCol, NormalColorCol_nom 


Find a local color from a normal vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void NormalColorCol( 

SVECTOR “vO, Pointer to normal vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

CVECTOR *v2) Pointer to color vector (output) 

void NormalColorCol_nom( 

SVECTOR *vO, Pointer to normal vector (input) 

CVECTOR *v7) Pointer to primary color vector (input) 

Explanation 

LLV = LLM * vO 

LC = BK + LCM * LLV 

v2 =v1*LC 

vO -> vx, vy, VZ (1, 3, 12) 


:(1, 3,12 
v1 ->1,g,b : (0, 8, O) 
NormalColorCol(): v2 -> r, g, b : (0, 8, 0) 


NormalColorCol_nom():The operation result(s) must be retrieved from the GTE (For further information, refer 
to the Inline Reference documentation): 





e = For (v2->r,v2->g,v2->b) use the read_rgb2 macro. 


See also 
NormalColor(), NormalColor3(), NormalColorCol3(), NormalColorDpq(), NormalColorDpq3() 
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8-78 Basic Geometry Library Functions 


NormalColorCol3, NormalColorCol3_nom 


Find a local color from three normal vectors. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void NormalColorCol3( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to normal vectors (input) 

CVECTOR *v3, Pointer to primary color vector (input) 


CVECTOR *v4, CVECTOR *v5, CVECTOR *v6) Pointer to color vectors (output) 


void NormalColorCol3_nom( 


SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to normal vectors (input) 
CVECTOR *v3) Pointer to primary color vector (input) 
Explanation 


(LLVO, LLV1, VVL2) = LLM * (vO, v1, v2) 
(LCO, LC1, LC2) = BK + LCM * (LLVO, LLV1, LLV2) 
(v4, v5, v6) = v3 * (LCO, LC1, LC2) 


VO, v1, V2 -> VX, Vy, VZ : (1,3, 12) 
v3 ->r,g, b : (0, 8, O) 
NormalColorCol8(): v4, v5, v6 -> r, g, b : (0, 8, O) 


NormalColorCol8_nom():The operation result(s) must be retrieved from the GTE (For further information, 
refer to the Inline Reference documentation): 








e For (v4,v5,v6) use the read_rgb_fifo macro. 


See also 
NormalColor(), NormalColor3(), NormalColorCol(), NormalColorDpq(), NormalColorDpq3\() 
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Basic Geometry Library Functions 8-79 


NormalColorDpq, NormalColorDpq_nom 


Find a local color from a normal vector and perform depth cueing. 





Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void NormalColorDpq( 

SVECTOR “vO, Pointer to normal vector (input) 

CVECTOR *v1, Pointer to primary color vector (input) 

long p, Interpolation value (input) 

CVECTOR *v2) Pointer to color vector (output) 


void NormalColorDpq_nom( 


SVECTOR “vO, Pointer to normal vector (input) 
CVECTOR *v1, Pointer to primary color vector (input) 
long p) Interpolation value (input) 
Explanation 

LLV = LLM * vO 


LC = BK + LCM * LLV 
v2=(1-p)*vi*LC+p*FC 


VO -> VX, VY, VZ : (1,3, 12) 
vl ->r,g, b : (0, 8, 0) 

p : (0, 20, 12) 
NormalColorDpq(): v2 -> r, g, b : (0, 8, 0) 


NormalColorDpq_nom():The operation result(s) must be retrieved from the GTE. (For further information see 
the Inline Reference documentation.): 





e = For (v2->r,v2->g,v2->b) use the read_rgb2 macro. 


See also 
NormalColor(), NormalColor3(), NormalColorCol(), NormalColorCol38(), NormalColorDpq38\() 
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8-80 Basic Geometry Library Functions 


NormalColorDpq3, NormalColorDpq3_nom 


Find local color from three normal vectors and perform depth cueing. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 
Syntax 


void NormalColorDpq3( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to normal vectors (input) 
CVECTOR *v3, Pointer to primary color vector (input) 
long p, Interpolation value (input) 

CVECTOR *v4, CVECTOR “v5, CVECTOR *v6) Pointer to color vectors (output) 


void NormalColorDpq3_nom( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to normal vectors (input) 


CVECTOR *v3, Pointer to primary color vector (input) 
long p) Interpolation value (input) 
Explanation 


(LLVO, LLV1, LLV2) = LLM * (vO, v1, v2) 
(LCO, LC1, LC2) = BK + LCM * (LLVO, LLV1, LLV2) 
(v4, v5, v6) = (1 -p) * v3 * (LCO, LC1, LC2) +p * FC 


VO, v1, V2 -> VX, Vy, VZ : (1,3, 12) 
v3 ->r,g, b : (0, 8, O) 

p : (O, 20, 12) 
NormalColorDpq3(): v4, v5, v6 -> r, g, b) : (0, 8, 0) 


NormalColorDpg3_nom():The operation result(s) must be retrieved from the GTE (For further information, 
refer to the Inline Reference documentation): 





e For (v4,v5,v6) use the read_rgb_fifo macro. 


See also 
NormalColor(), NormalColor3(), NormalColorCol(), NormalColorCol8(), NormalColorDpq() 
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Basic Geometry Library Functions 8-81 


otz2p 

Get depth cueing interpolation value p from OTZ value. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long otz2p( 

long otz, OTZ 

long projection) Distance between visual point and screen 

Explanation 


Get the approximate depth cueing interpolation value p from otz, which is 1/4 of sz, the z element of the 
screen coordinates. 


Depending on the fog setting, errors can increase and the results are not necessarily the same as with 
RotTransPers() functions. 


Return value 
Depth cueing interpolation value p (0: 0%, 4096 : 100%). 


See also 
p2otz() 
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8-82 Basic Geometry Library Functions 


OuterProduct0O 

Outer product of two vectors. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 


void OuterProduct0( 
VECTOR *vO, VECTOR “v7, Pointer to vectors (input) 


VECTOR *v2) Pointer to vector (output) 
Explanation 

Returns the outer product vector of two vectors vO and v7 to v2. 
VO, v1 -> VX, VY, VZ : (1, 31, 0) 

V2 -> VX, VY, VZ : (1, 31, O) 

See also 


NormalClip(), OuterProduct1 2() 
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OuterProduct12 


Outer product of two vectors. 


Library Header File Introduced 
libgte. lib libgte.h 2.X 


Syntax 

void OuterProduct1 2( 

VECTOR “vO, VECTOR *v7, Pointer to vectors (input) 
VECTOR *v2) Pointer to vector (output) 


Explanation 
Returns the outer product vector of two vectors, vO and v7, to v2. 


vO, v1, V2 -> vx, vy, yz : (1, 19, 12) 


See also 
NormalClip(), OuterProductO() 
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Basic Geometry Library Functions 8-83 


Documentation Date 
12/14/98 
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8-84 Basic Geometry Library Functions 





p2otz 

Get otz from depth cueing interpolation value. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long p2otz( 

long p, Interpolation value (O to 4096 ) 

long projection) Distance between visual point and screen 

Explanation 

Gets the otz value, which is 1/4 of sz (screen coordinate z element) from the depth cueing interpolation 

value p. 


Depending on the fog setting, errors can increase and the results are not necessarily the same as with 
RotTransPers() functions. 


otz when P=0 or p=4096 is not theoretically decided as identification, but with this function a convenient 
value is returned. 


Return value 
OTZ value. 


See also 
otz2p() 
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Basic Geometry Library Functions 8-85 


pers_map 
Perspective conversion texture mapping. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.2 12/14/98 
Syntax 
void pers_map( 
int abuf, ID of displayed buffer 
SVECTOR **vertex, 3 dimensional coordinates of 4 vertices 
int tex/4][2], Texture address of 4 vertices 
u_short *dtext) Pointer to texture storage location converted to direct color 
Explanation 


Performs texture mapping with no distortion. 
Flat texture, with no light source calculations only. 
The 4 vertices are only square, rectangle and parallelogram locations. 


Z sort by OT is not possible. 
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8-86 Basic Geometry Library Functions 


PhongLine 

Phong shading. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 

Syntax 

void PhongLine( 

int /start_x, X coordinate of starting point 

int jend _x, X coordinate of finishing point 

int p, Differential X coordinate of fs value 

int g, Differential caused by X coordinate of ft value 

u_short “pixx, Pixel pointer 

int fs, Interpolation coefficient at start point 

int ft, Interpolation coefficient at start point 

int /4, (Line number) %4 due to dithering 

int det) Queue method of edge queue 

Explanation 


Performs one line Phong shading. For more information, refer to sample program (sample/graphics/phong) 
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Basic Geometry Library Functions 8-87 


PopMatrix 

Reset a constant rotation matrix from a stack. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void PopMatrix(void) 


Explanation 
Resets a constant rotation matrix from a stack. 


See also 
PushMatrix() 
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8-88 Basic Geometry Library Functions 


PushMatrix 


Save a constant rotation matrix in a stack. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 
void PushMatrix(voic) 


Explanation 
Saves a constant rotation matrix on a stack. The stack has 20 slots. 


See also 
PopMatrix() 
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Basic Geometry Library Functions 8-89 


ratan2 


Arctan. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 


long ratan2( 
long x, long y) Value 


Explanation 
Uses PlayStation format (4096 = 360 degrees = 2pai) to finish the x/y arctan function (-180 degrees and 
+180 degrees, -pai...pai). 


Return value 
atan2 (x, y) : (1, 19, 12) 


The return value is incorrect if either x or y is -2147483648 (0x80000000 = long negative maximum value). 


See also 
catan(), rcos(), rsin() 
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8-90 Basic Geometry Library Functions 


rcos 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 


int rcos( 
int a) Angle (in PlayStation format) 


Explanation 
Finds the cosine function of the angle (in PlayStation format) (4096 = 360 degrees = 2pai) using fixed-point 
math (where 4096=1.0). 


Compared to ccos(),rcos() is faster and takes up more space. 


a : PlayStation format (4096 = 360 degrees = 2pai) 


Return value 
cos (a) : (1, 19, 12) 


See also 
ccos(), ratan2(), rsin() 
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Basic Geometry Library Functions 8-91 


RCpolyF3, RCpolyFT3, RCpolyG3, RCpolyGT3 


Triangle division functions. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

u_long *RcpolyF3(POLY_F3 *s, DIVPOLYGONS “divp) Flat triangle. 


u_long *RcpolyFT3(POLY_FT3 *s, DIVPOLYGONS “divp) Flat, textured triangle. 
u_long *RcpolyG3(POLY_G3 *s, DIVPOLYGONS “divp) Gouraud-shaded triangle 
u_long *RcpolyGT3(POLY_GT3 *s, DIVPOLYGONS “divp) |Gouraud-shaded, textured triangle 


Explanation 


These are recursive functions for division of triangles. s is a pointer to the GPU packet buffer address. divp 
is a pointer to a division work area. You must set the data below in the divp work area: 


u_long ndiv Number of divisions 

u_long pih, piv Display screen resolution (for clipping) 
u_short clut, tpage CBA & TSB 

CVECTOR rgbc Color vector (+code) 

u_long *ot OT entry 

RVECTOR 10, r7, r2 Division vertex vector data 

CRVECTORS cr{5] 2D and 3D texture coordinates and color 


for each vertex 


Assign the vertex vector data of CRVECTORS (cr[5)) to the value of the vertex vector data of RVECTORs rO, 
r1, and r2. 


Note: See DIVPOLYGONS for a full description of divp. 





Return value 
Updated GPU packet buffer address 


See also 
RCpolyF4() 
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8-92 Basic Geometry Library Functions 


RCpolyF4, RCpolyFT4, RCpolyG4, RCpolyGT4 


Quadrilateral division functions. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

u_long *RcpolyF4(POLY_F4 *s, DIVPOLYGON4 “divp) Flat quadrilateral. 


u_long *RcpolyFT4(POLY_FT4 *s, DIVPOLYGON4 “divp) Flat, textured quadrilateral. 

u_long *RcpolyG4(POLY_G4 *s, DIVPOLYGON4 “divp) Gouraud-shaded quadrilateral 

u_long *RcpolyGT4(POLY_GT4 *s, DIVPOLYGON4 “divp) Gouraud-shaded, textured 
quadrilateral 


Explanation 


These are recursive functions for division of quadrilaterals. s is a pointer to the GPU packet buffer address. 
divp is a pointer to a division work area. You must set the data below in the divp work area: 


u_long ndiv Number of divisions 

u_long pih, piv Display screen resolution (for clipping) 
u_short clut, tpage CBA & TSB 

CVECTOR rgbc Color vector (+code) 

u_long *ot OT entry 

RVECTOR rO, r7, r2 Division vertex vector data 

CRVECTOR4 cr{5] 2D and 3D texture coordinates and color 


for each vertex 


Assign the vertex vector data of CRVECTOR4 (cr[5)) to the value of the vertex vector data of RVECTORs rO, 
r7,r2andr3. 


Note: See DIVPOLYGON4 for a full description of divp. 


Return value 
Updated GPU packet buffer address 


See also 
RCpolyF3() 
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Basic Geometry Library Functions 8-93 


ReadColorMatrix 


Read a local color matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 


void ReadColorMatrix( 
MATRIX *m) Pointer to matrix (input) 


Explanation 
Reads the current local color matrix, and saves it in m. 


m ->m [i] fl: (1, 3, 12) 


CONFIDENTIAL Run-Time Library Reference 


8-94 Basic Geometry Library Functions 


ReadGeomOffset 
Read GTE offset value. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 


void ReadGeomOffset( 
long *ofx, Pointer to offset X coordinate 
long *ofy) Pointer to offset Y coordinate 


Explanation 
Reads the GTE offset value. 


ofx, ofy : (0, 32, O) 
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Basic Geometry Library Functions 8-95 


ReadGeomScreen 

Read distance from viewpoint to screen. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

long 

ReadGeomScreen(voic) 

Explanation 


Reads the distance h from the viewpoint (eye) to the screen. 


Return value 
h value 
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8-96 Basic Geometry Library Functions 


ReadLightMatrix 


Read a local light matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 


void ReadLightMatrix( 
MATRIX *m) Pointer to matrix (input) 


Explanation 
Reads the current local light matrix, and saves it in m. 


m ->m [i] fl: (1, 3, 12) 
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Basic Geometry Library Functions 8-97 


ReadRGBfifo 

Read RGBcd values. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void ReadRGBfifo( 
CVECTOR *v0, CVECTOR *v1, CVECTOR *v2) Pointer to vectors (output) 


Explanation 
Stores the RGBcdO, RGBcd1, and RGBcd2 values in vO, v7, and v2. 


vO, v1, v2 -> r, g, b, cd: (0, 8, 0) 


See also 
ReadSxS/Yfifo(), ReadSZfifo3(), ReadSZfifo4() 
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8-98 Basic Geometry Library Functions 


ReadRotMatrix 

Read a constant rotation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void ReadRotMatrix( 

MATRIX *m) Pointer to matrix (output) 

Explanation 

Reads the current rotation matrix, and saves it in m. 

m ->m [i] [j] (1, 3, 12) 

m ->t [i] : (1,31, 0) 
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Basic Geometry Library Functions 8-99 


ReadSXSYVfifo 

Read SXSY values. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void ReadSXSYfifo( 
long *sxy0, long*sxy7, long *sxy2) Pointers to screen x,y values 


Explanation 
Stores the sxO, syO, sx1, sy1, sx2, and sy2 values in sxy0, sxy7, and sxy2. 


(sxyO, sxy7, sxy2) : (1, 15, O) 


See also 
ReadRGBfifo(), ReadSZfifo3(), ReadSZfifo4() 
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8-100 Basic Geometry Library Functions 


ReadSZfifo3 


Read SZ values. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 


void ReadSZfifo3( 
long *sz0, *sz7, “sz2) Pointers to SZ values 


Explanation 
Stores the szO, sz1, and sz2 values in szO, sz7, and sz2. 


(szO, sz1, $z2) : (O, 16, 0) 


See also 
ReadRGBfifo(), ReadSXSYfifo(), ReadSZfifo4() 
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Basic Geometry Library Functions 8-101 


ReadSZfifo4 

Read SZ values. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


void ReadSZfifo4( 
long *szx, long *szO, long *sz7, long *sz2) Pointers to SZ values 


Explanation 
Stores the szx, sz0, sz1, and sz2 values in szx, szO, sz7, and sz2. 


(szx, SZO, SZ71, Sz2) : (O, 16, 0) 


See also 
ReadRGBfifo(), ReadSXSYfifo(), ReadSZfifo3() 
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8-102 Basic Geometry Library Functions 


RotAverage3, RotAverage3_nom 


Perform coordinate and perspective transformation for 3 points, and get interpolation value and average of 
Z values for depth cueing. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Syntax 


long RotAverage3( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointers to vectors (input) 


long *sxy0, long “sxy7, long *sxy2, Pointers to coordinates (output) 
long *p, Pointers to interpolation values (output) 
long *flag) Pointer to flag (output) 


long RotAverage3_nom 
(SVECTOR *vO, SVECTOR *v7, SVECTOR *v2) Pointer to vectors (input) 


Explanation 

A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sxy0, sxy7, and sxy2 are returned. 
An interpolation value for depth cueing on v2 to p is also returned. The return value becomes the average 
of three screen coordinate Z values. 





VO, v1, V2 -> vx, vy, vz : (1, 15, 0) 

sxy0O, sxy7, Sxy2 > (1, 15, O), (1, 15, 0) 
p : (O, 20, 12) 

flag : (0, 32, 0) 


RotAverage3_nom():The operation result(s) must be retrieved from the GTE. (For further information, refer 
to the Inline Reference documentation.) 





For (SzO,sz1,sz2) use macro read_sz_fifo3 

For ((sxO,sy0),(Sx1,sy1),(Sx2,sy2)) use macro read_sxsy_fifo3 
For p use macro read_p 

For otz use macro read_otz. 

flag is returned in register vO. 


Return value 
OTZ value 


(RogAverage3_nom() returns no value) 


See also 
RotAverage4(), RotAverageNclip3(), RotAverageNclipColorCol3(), RotAverageNclioColorDpq3i), 
RotColorDpqs\() 
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Basic Geometry Library Functions 8-103 


RotAverage4 


Perform coordinate transformation for 3 points and perspective transformation, and find an interpolation 
value and an average of Z values for depth cueing. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 
Syntax 


long RotAverage4( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR *v3, Pointer to vectors (input) 


long *sxy0, long *sxy1, long *sxy2, long *sxy3, Pointer to coordinates (output) 
long *p, Pointer to interpolation (output) 
long *flag) Pointer to flag (output) 
Explanation 


A coordinate transformation of four points vO, v7, v2 and v3 is performed using a rotation matrix. Next a 
perspective transformation is performed and four screen coordinates sxyO, sxy7, sxy2, and sxy3 are 
returned. An interpolation value for depth cueing on v2 to p is also returned. 


vO, v1, V2, V3 -> vx, vy, vz: (1, 15,0) 


SXy0, Sxy7, Sxy2, Sxy3 : (1, 15, 0), (1, 15, 0) 
p : (0, 20, 12) 
flag : (0, 32, 0) 


Return value 
1/4 (OTZ value) average of four screen coordinate Z values. 


See also 
RotAverage3(),RotAverageNclip4() 
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8-104 Basic Geometry Library Functions 


RotAverageNclip3 


Perform coordinate transformation and perspective transformation for three points, and find an interpolation 
value, average of Z values, and outer product. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Syntax 


long RotAverageNclip3( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 


long *sxy0, long “sxy7, long *sxy2, Pointer coordinates (output) 
long *p, Pointer to interpolation (output) 
long *oiz, Pointer to OTZ value (output) 
long *flag) Pointer to flag (output) 
Explanation 


A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sxy0, sxy7, and sxy2 are returned. 
An interpolation value for depth cueing on v2 to p is also returned. Finally, we also receive 1/4 of the Z value 
of the screen coordinates for v2 to otz. 


VO, v1, V2 -> vx, vy, vz :(1, 15, 0) 
sxy0, SXy1, Sxy2 > (1, 15, O), (1, 15, 0) 
p : (O, 20, 12) 
otz : (0, 32, 0) 
flag : (0, 32, 0) 





When the return value is negative, SX, SY, etc. are incorrect. When SX and SY are required, use 
RotAverage3(). 


Return value 
Outer product of (sxO, sy0), (Sx1, sy1), (Sx2, sy2). 


See also 
RotAverage3(), RotAverageNclip4(), RotAverageNclip3_nom(), RotAverageNclipColorCol3(), 
RotAverageNclipColorDpq3(), RotColorDpaq3i\) 
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Basic Geometry Library Functions 8-105 


RotAverageNclip3_nom 


Perform coordinate transformation and perspective transformation for three points, and find an interpolation 
value, average of Z values, and outer product. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte. lib libgte.h 2.x 12/14/98 
Syntax 


long RotAverageNclip3_nom 
(SVECTOR *vO, SVECTOR *v7, SVECTOR *v2) Pointer to vectors (input) 


Explanation 

After performing coordinate transformation for local coordinate vectors vO, v1, and v2 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates sxO, syO, 
szO, sx1, sy1, $z1, sx2, sy2, and sz2, the interpolation value p for depth cueing corresponding to v2, an 
average of Z values (otz) for the three screen coordinates, and an outer product value (opz) for (sx0,sy0), 
(sx1,sy1), and (sx2,sy2) in GTE's internal register. 





The argument format and data format are as follows: 
VO, v1, V2 -> vx, vy, vz: (1, 15, 0) 


sy0, sxO, SZO (1, 15, 0), (1, 15, O), (0, 16, 0) 
Sx1, SX1, sz1 :(1, 15, 0), 1, 15, 0) (O, 16, 0) 
SX2, Sy2, SZ2 : (1, 15, 0), (1, 15, 0) (O, 16, 0) 
p (0, 20, 12 
otz : (0, 32, 0) 
flag : (0, 32, 0) 


The operation result(s) must be retrieved from the GTE. (For further information, refer to the Inline 
Reference documentation.) 


(sz0,sz1,Sz2) is read by macro read_sz_fifo3 
((sx0,sy0),(Sx1,sy1),(Sx2,sy2)) is read by macro read_sxsy_fifo3 
p is read by macro read_p 

otz is read by macro read_otz 

opz is read by macro read_opz 


Return value 
None 


See also 


RotAverage3(),RotAverageNclip3(), RotAverageNclip4(), RotAverageNclipColorCol3(), 
RotAverageNclipColorDpq3(), RotColorDpgq3\() 
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8-106 Basic Geometry Library Functions 


RotAverageNclip4 


Perform a coordinate transformation and perspective transformation for four points; find an interpolation 
value, average of Z values, and outer product. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Syntax 


long RotAverageNclip4( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR *v3, Pointer to vectors (input) 


long *sxy0, “sxy7, *sxy2, “sxy3, Pointer to coordinates (output) 

long *p, Pointer to interpolation value 
(output) 

long *oiz, Pointer to OTZ value (output) 

long *flag) Pointer to flag (output) 

Explanation 


A coordinate transformation of four points vO, v7, v2, and v3 is performed using a rotation matrix. Next a 
perspective transformation is performed and four screen coordinates sxy0, sxy7, sxy2 and sxy3 are 
returned. An interpolation value for depth cueing on v2 to p is also returned. Finally, we also receive 1/4 of 
the Z value of the screen coordinates for v2 to otz. 





vO, v1, V2, V3 -> VX, VY, VZ : (1, 15, 0) 

SxyO, Sxy7, Sxy2, Sxy3 : (1, 15, 0), (1, 15, 0) 
p : (0, 20, 12) 

otz : (0, 32, O) 

flag (0, 32, 0) 


When the return value is negative, SX, SY, etc., are incorrect. When SX and SY are required, use 
RotAverage4(). 





Return value 
Outer product of (sx0, sy0), (sx1, sy1), (Sx2, sy2). 


See also 
RotAverage4(), RotAverageNclip3\() 
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RotAverageNclipColorCol3 


Basic Geometry Library Functions 8-107 


Perform a coordinate transformation for three points, perspective transformation, and find a color. 


Library Header File 
libgte. lib libgte.h 
Syntax 


long RotAverageNclipColorCol3( 

SVECTOR “vO, SVECTOR *v7, SVECTOR *v2, 
SVECTOR “v3, *v4, *v5, 

CVECTOR *v6, 

long *sxy0, “sxy7, *sxy2, 

CVECTOR *v7, *v8, *v9, 


Documentation Date 
12/14/98 


Introduced 
2.X 


Pointer to vectors (input) 

Pointer to normal vectors (input) 
Pointer to primary color vector (input) 
Pointer to coordinate values (output) 
Pointer to color vectors (output) 


long *oiz, Pointer to OTZ value (output) 
long *flag) Pointer to flag (output) 
Explanation 


A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and four screen coordinates sxy0, sxy7, sxy2 are returned. The 
remaining values are calculated as follows: 


(LLVO, LLV1, LLV2) = LLM * (v3, v4, v5) 
(LCO, LC1, LC2) = BK + LCM * (LLVO, LLV1, LLV2) 


(v7, v8, v9) = v6 * (LCO, LC1, LC 2) 
(separate multiplications) 


The function also returns an average of Z values of three screen coordinates to otz. 


VO, v1, V2 -> VX, VY, VZ : (1, 15, 0) 

V3, V4, V5 -> VX, VY, VZ „(1 3, 12) 

v6 ->r,g, b : (0, 8, O) 

SXy0, Sxy7, SXy2 : (1, 15, O), (1, 15, 0) 
v7, V8, V9 ->1r, g, b : (0, 8, O) 

otz : (0, 32, 0) 

flag : (0, 32, 0) 


When the return value is negative, SX, SY, etc., are incorrect. 


Return value 
Outer product of (sxO, sy0), (sx1, sy1), (Sx2, sy2) 


See also 


RotAverage3(),RotAverageNclip3(), RotAverageNclipColorCol38_nom(), RotAverageNclipColorDpq3i), 
RotColorDpqs\() 
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8-108 Basic Geometry Library Functions 


RotAverageNclipColorCol3_nom 


Perform a coordinate transformation for three points, perspective transformation, and find a color. Results 
obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Syntax 


long RotAverageNclipColorCol3_nom( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 

SVECTOR *v3, SVECTOR *v4, SVECTOR “v5, Pointer to normal vectors (input) 
CVECTOR *v6) Pointer to primary color vector (input) 


Explanation 


After performing coordinate transformation for local coordinate vectors vO, v1, and v2 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates sxO, syO, 
szO, sx1, sy1, $z1, Sx2, sy2, and sz2, an average of Z values (otz) for the three screen coordinates, and an 
outer product value (opz) for (sxO,sy0), (sx1,sy1), and (Sx2,sy2) in GTE's internal register. 


(LLVO, LLV1, LLV2) = LLM * (v3, v4, v5) 
(LCO, LC1, LC2) = BK + LCM * (LLVO, LLV1, LLV2) 
(V7, v8, v9) = v6 * (LCO, LC1, LC2) 


VO, v1, V2 -> VX, Wy, VZ 
V3, V4, V5 -> VX, VY, VZ 
SxO, Sy0,SzO 

sx1, sy1,sz1 

SX2, SY2,SZ2 

v6 ->r, g, b 

V7, V8, v9 ->1,g,b 

otz 

flag 
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The operation result(s) must be retrieved from the GTE (For further information, refer to the Inline Reference 
documentation): 





(szO,sz1,sz2) is read by macro read_sz_fifo3 
((sxO,sy0),(Sx1,sy1),(Sx2,sy2)) is read by macro read_sxsy_fifo3 
((rO,g0,b0), (r1,g1,b1), (r2,g2,b2)) is read by macro read_rgb_fifo 
p is read by macro read_p 

otz is read by macro read_otz 

opz is read by macro read_opz 

flag is returned in register vO. 


Return value 
None. 


See also 


RotAverage3(), RotAverageNclip3(), RotAverageNclipColorCol3(), RotAverageNclioColorDpqg3i), 
RotColorDpqs\() 
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RotAverageNclipColorDpq3 


Basic Geometry Library Functions 8-109 


Perform coordinate transformation for three points, perspective transformation, and depth cueing. 


Library Header File 
libgte. lib libgte.h 
Syntax 


long RotAverageNclipColorDpq3( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, 
SVECTOR *v3, SVECTOR *v4, SVECTOR “v5, 
CVECTOR “v6, 

long *sxy0, long “sxy7, long *sxy2, 


CVECTOR *v7, CVECTOR *v8, CVECTOR *v9, 


Introduced Documentation Date 
2X 12/14/98 


Pointer to vectors (input) 

Pointer to normal vectors (input) 
Pointer to primary color vector (input) 
Pointer to coordinate values (output) 
Pointer to color vectors (output) 


long *otz, Pointer to OTZ value output) 
long *flag) Pointer to flag (output) 
Explanation 


A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sxy0, sxy1, and sxy2 are returned. 
The function uses the interpolation value p for depth cueing; p is found by the following calculations: 


(LLVO, LLV1, LLV2) = LLM x (v3, v4, v5) 
(LCO, LC1, LC2) = BK + LCM x (LLVO, LLV1, LLV2) 
(v7, v8, v9) = (1-p) x v6 x (LCO, LC1, LC2) + p x FC 


where v6 x ( LCO, LC1, LC2) indicates a separate multiplication. 





The function also returns an average of the Z values of the three screen coordinates to otz. 


vO, v1, V2 -> VX, VY, VZ : (1, 15, 0) 

V3, V4, V5 -> VX, VY, VZ (1, 3, 12) 

v6 ->r, g, b : (0, 8, 0) 

SXy0, Sxy7, Sxy2 (1, 15, O), (1, 15, 0) 
v7, V8, V9 ->r, g, b : (0, 8, O) 

otz : (0, 32, 0) 

flag : (0, 32, 0) 


When the return value is negative, SX, SY, etc. are incorrect. 


Return value 
Outer product of (sx0, sy0), (Sx71, sy7), (Sx2, sy2) 


See also 


RotAverage3(), RotAverageNclip3(), RotAverageNclipColorCol3(), RotAverageNclipColorDpq3_nom(), 
RotColorDpqs\() 
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8-110 Basic Geometry Library Functions 


RotAverageNclipColorDpq3_nom 


Perform coordinate transformation for three points, perspective transformation, and depth cueing. Results 
obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Syntax 


long RotAverageNclipColorDpq3_nom( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 

SVECTOR *v3, SVECTOR *v4, SVECTOR *v5, Pointer to normal vectors (input) 
CVECTOR “*v6) Pointer to primary color vector (input) 


Explanation 


After performing coordinate transformation for local coordinate vectors vO, v1, and v2 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates sxO, syO, 
szO, sx1, sy1, sz1, Sx2, sy2, and sz2, an average of Z values (otz) for the three screen coordinates, and an 
outer product value (opz) for (sxO,sy0), (sx1,sy1), and (Sx2,sy2) in GTE's internal register. The interpolation 
value p is used in the calculation below for the desired depth cueing. 


(LLVO, LLV1, LLV2) = LLM x (v3, v4, v5) 
(LCO, LC1, LC2) = BK + LCM x (LLVO, LLV7, LLV2) 
(V7, v8, v9) = (1-p) x v6 x (LCO, LC 1, LC2) + p x FC 





The argument and internal data format is as follows: 


VO, v1, V2 -> VX, Vy, VZ : (1, 15, 0) 

V3, V4, V5 -> VX, VY, VZ : (1, 3, 12) 

v6 ->r,g, b (0, 8, 0) 

sx0, sy0, sz0O :(1,15,0), (1,15,0), (0,16,0) 
sx1, sy1, sz1 (1,15,0), (1,15,0), (0,16,0) 
SX2, SY2, SZ2 : (1,15,0), (1,15,0), (0,16,0) 
V7,V8,V9 -> r,9,b : (0,8,0) 

otz : (0,32,0) 

flag : (0,32,0) 





The operation result(s) must be retrieved from the GTE (For further information, refer to the Inline Reference 
documentation): 


(sz0,sz1,sz2) is read by macro read_sz_fifo3 
((sx0,sy0),(Sx1,sy1),(Sx2,sy2)) is read by macro read_sxsy_fifo3 
((rO,g0,b0), (r1,g1,b1), (r2,g2,b2)) is read by macro read_rgb_fifo 
p is read by macro read_p 

otz is read by macro read_otz 

opz is read by macro read_opz 

flag is returned in register vO. 


Return value 
None. 


See also 
RotAverage3(), RotAverageNclip3(), RotAverageNclipColorCol3(), RotAverageNclioColorDpq3i), 
RotColorDpqs\() 
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Basic Geometry Library Functions 8-111 


RotColorDpq 

Perform coordinate transformation for one point, perspective transformation, and depth cueing. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotColorDpq( 

SVECTOR “vO, Pointer to vector (input) 

SVECTOR “v7, Pointer to normal vector (input) 

CVECTOR *v2, Pointer to primary color vector (input) 

long *sxy, Pointer to coordinate values (output) 

CVECTOR “v3, Pointer to color vector (output) 

long *flag) Pointer to flag (output) 

Explanation 


A coordinate transformation for the point vO is performed using a rotation matrix. Next a perspective 
transformation is performed and the screen coordinate sxy is returned. The function uses the interpolation 
value p for depth cueing, which is found by the following calculations: 


LLV=LLM xvi 
LC = BK + LCM x LLV 
v3 = (1-0) x v2x LC + x FC 








where v2 x LC indicates a separate multiplication. 


VO -> VX, VY, VZ > (1, 15, O) 

V1 -> VX, W, VZ : (1, 3, 12) 

v2 ->1r,g,b (0, 8, 0) 

SXY (1, 15, 0), (1, 15, 0) 
v3 ->r,g, b : (0, 8, O) 

flag : (0, 32, 0) 


Return value 
1/4 of the Z component sz of the screen coordinates. 


See also 
RotColorDpq_nom(), RotColorDpq3s\() 
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RotColorDpq_nom 


Perform coordinate transformation for one point, perspective transformation, and depth cueing. Results 
obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotColorDpq_nom( 

SVECTOR “vO, Pointer to vector (input) 

SVECTOR “v7, Pointer to normal vector (input) 

CVECTOR *v2) Pointer to primary color vector (input) 

Explanation 


A coordinate transformation for the point vO is performed using a rotation matrix. Next a perspective 
transformation is performed and the screen coordinates (sx,sy,sz) are stored in the GTE internal register. 
The function uses the interpolation value p for depth cueing and stores the obtained color vector v3 in the 
internal register which is found by the following calculations: 


LLV=LLM xvi 
LC = BK + LCM x LLV 
v3 = (1-0) x v2x LC +pxFC 








where v2 x LC indicates a separate multiplication. 


vO -> VX, VY, VZ > (1, 15, O) 

V1 -> VX, VY, VZ >(1, 3, 12) 

SX, SY,SZ : (1,15,0), (1,15,0), (0,16,0) 
v2 ->1r,g,b : (0, 8, O) 

v3 ->r,g, b : (0, 8, O) 

flag : (0, 32, 0) 





The operation result(s) must be retrieved from the GTE (For further information, refer to the Inline Reference 


documentation): 

e szis read by macro read_sz2 

e = (s5x,sy) is read by macro read_sxsy2 
e pisread by macro read_p 

e v3 is read by macro read_rgb2 

e 


flag is returned in register vO. 


Return value 
None. 


See also 
RotColorDpq(), RotColorDpq3\() 
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RotColorDpq3 

Perform coordinate transformation for three points, perspective transformation, and depth cueing. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


long RotColorDpq3( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 
SVECTOR *v3, SVECTOR *v4, SVECTOR “v5, Pointer to normal vectors (input) 


CVECTOR “v6, Pointer to primary color vector (input) 
long *sxy0, long “sxy7, long *sxy2, Pointer to coordinates (output) 
CVECTOR *v7, CVECTOR *v8, CVECTOR *v9, Pointer to color vectors (output) 

long *flag) Pointer to flag (output) 

Explanation 


A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sxy0, sxy7, and sxy2 are returned. 
The function uses the interpolation value p for depth cueing, which is found by the following calculations: 


LLVO, LLV1, LLV2) = LLM x (v3, v4, v5) 

(LCO, LC1, LC2) = BK + LCM x (LLVO, LLV7, LLV2) 

(V7, v8, v9) = (1-p) x v6 x (LCO, LC 1, LC2) + p x FC 

where v6 x (LCO, LC 1, LC2) indicates a separate multiplication. 





vO, V1, V2 -> VX, VY, VZ : (1, 15, 0) 

V3, V4, V5 -> VX, VY, VZ (1, 3, 12) 

v6 ->r,g, b : (0, 8, O) 

SXy0, sxy7, Sxy2 > (1, 15, O), (1, 15, 0) 
v7, V8, V9 ->r, g, D : (0, 8, O) 


flag : (0, 32, 0) 


Return value 
1/4 of the Z component sz of the screen coordinates. 


See also 
RotColorDpq(), RotColorDpg3_nom() 


CONFIDENTIAL Run-Time Library Reference 


8-114 Basic Geometry Library Functions 


RotColorDpq3_nom 


Perform coordinate transformation for three points, perspective transformation, and depth cueing. Results 
obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotColorDpq3_nom 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 

SVECTOR *v3, SVECTOR *v4, SVECTOR “v5, Pointer to normal vectors (input) 

CVECTOR *v6) Pointer to primary color vector (input) 

Explanation 


A coordinate transformation of three points vO, v7, v2 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sxO, syO, szO, sx7, sy1, SZ1, Sx2, sy2 
and sz2 are stored in the GTE internal register. The function uses the interpolation value p for depth cueing 
and stores the obtained color vector in the internal register which is found by the following calculations: 


LLVO, LLV1, LLV2) = LLM x (v3, v4, v5) 
(LCO, LC1, LC2) = BK + LCM x (LLVO, LLV7, LLV2) 
(V7, v8, v9) = (1-p) x v6 x (LCO, LC1, LC2) + p x FC 





VO, v1, V2 -> VX, VY, VZ : (1, 15, 0) 

V3, V4, V5 -> VX, Vy, VZ (1, 3, 12) 

v6 -> 1, g, b (0, 8, 0) 

sxy0, sxy7, Sxy2 > (1, 15, 0), (1, 15, 0) 
V7, V8, v9 ->r, g, b (0, 8, 0) 

flag (0, 32, 0) 





The operation result(s) must be retrieved from the GTE (For further information, refer to the Inline Reference 
documentation): 


e sz0,sz1,Sz2) is read by macro read_sz_fifo3 
e  ((sx0,sy0),(sx2,sy2), (Sx2,Sy2)) is read by macro read_sxsy_fifo3 
e pis read by macro read_p and v7,v8,v9 is read by macro read_rgb_fifo. flag is returned in register vO. 


See also 
RotColorDpq(), RotColorDpq3\() 
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RotColorMatDpq 

Perform coordinate transformation, perspective transformation, and depth cueing. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotColorMatDpq( 

SVECTOR “vO, Pointer to vector (input) 

SVECTOR “v7, Pointer to normal vector (input) 

SVECTOR *v2, Pointer to primary color vector (input) 

long *sxy, Pointer to coordinate values (output) 

CVECTOR “v3, Pointer to color vector (output) 

long matc, Material (input) 

long flag) Address where a flag will be stored 

Explanation 


A coordinate transformation for the point vO is performed using a rotation matrix. Next a perspective 
transformation is performed and the coordinate sxy is returned. The function uses the interpolation value p, 
found by the following calculations, for depth cueing. 


LLV=LLM xv1 

LLV =LLVA (24matc) 

LC = BK + LCM x LLV 

v3 = (1-0) x v2x LC + x FC 





where v2 x LC indicates a separate multiplication. 


VO -> VX, VY, VZ (1, 15, 0) 

V1 -> VX, VY, VZ : (1, 3, 12) 

v2 ->r,9g, b (0, 8, 0) 

SXY (1, 15, 0), (1, 15, 0) 
v3 ->1r,g,b : (0, 8, O) 

matc : (0, 32, 0) 

flag : (0, 32, 0) 


Return value 
1/4 of the Z component sz of screen coordinates. 


See also 
RotColorDpq() 
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RotMatrix... 


Find rotation matrix from a rotation angle. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.3 12/14/98 

Syntax 

MATRIX *RotMatrix( 

SVECTOR *r, Input: rotation angle 

MATRIX *m) Output: rotation matrix 


MATRIX *RotMatrixXZY(SVECTOR *r, MATRIX *m) 
MATRIX *RotMatrixYXZ(SVECTOR *r, MATRIX *m) 
MATRIX *RotMatrixYZX(SVECTOR *r, MATRIX *m) 
MATRIX *RotMatrixZXY(SVECTOR *r, MATRIX *m) 
MATRIX *RotMatrixZYX(SVECTOR *r, MATRIX *m) 


Explanation 
Matrix m is set to a rotation matrix according to the rotation angle (r[O],r{1],/[2)). 


A rotation angle value of 4096 is equivalent to 360 degrees. A matrix element value of 4096 is equivalent to 
1.0. 


When matrix is: 


cO=cos(r[0]), | sO=sin(r[O}) 
ct=cos([1]),  st=sin(r[1]) 
c2 = cos(r[2]), s2 = sin(r[2]) 
1 0 0 cl 0 si c2 -s2 0 
mX=|0 cO -s0 mY=| O 1 0 mZ=|s2 c2 0 
O sO cO -s1 0 ct 0O 0 1 


it is the result of the following product: 








Table 8-2 

Function name Matrix calculation formula Rotation sequence 

RotMatrix mX x mY x mZ Z axis -> Y axis -> X axis 
RotMatrixxZY mX x mZ x mY Y axis -> Z axis -> X axis 
RotMatrixYXZ mY x mX x mZ Z axis -> X axis -> Y axis 
RotMatrixYZX mY x mZ x mX X axis -> Z axis -> Y axis 
RotMatrixZXY mZ x mX x mY Y axis -> X axis -> Z axis 
RotMatrixZYX mZ x mY x mX X axis -> Y axis -> Z axis 





In GTE coordinate conversion functions such as RotTransPers(), the vector is applied from the 
right side. For example, with RotMatrix(), the rotation is performed in the following sequence: Z 


axis, Y axis, X axis. 
Parameter format: 


m->mlilii] : (1,3,12) 


f->VX,Vy,VZ : (1,3,12) (where 360 degrees is 1.0) 


Return value 
m 
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See also 


RotMatrix_gte(), RotMatrixC(), RotMatrixX(), RotMatrixY(), RotMatrixYXZ_gte(), RotMatrixZ(), 
RotMatrixZYX_gte() 
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RotMatrix_gte 


Find a rotation matrix from a rotation angle. Approximately 2 X faster than RotMatrix(). 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

MATRIX *RotMatrix_gte( 

SVECTOR “fr, Pointer to rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (output) 

Explanation 


Generates a rotation queue from the rotation angle (r[0], [1], [2]) in matrix m. A value of 4096 represents 
360 degrees; and in matrices, 4096 represents 1.0. 


The matrix is obtained by doing the following multiplication. In a coordinate conversion function such as 
RotTransPers() for GTE, a vector is multiplied beginning with the rightmost end. So, it is rotated around the 
Z-, Y-, and X-axes. 


1 0O O cl O si c2 -s2 0 
O cO -s0|*| O 1 O]*/s2 c2 0 


O sO cO -s1 0 c1 Oo 0 1 
However, 
cO=cos (r[0]) ,sO=sin (r[0]) 
c1=cos (r[1]) S1=sin (r[1]) 
c2=cos (r[2]) S2=sin (r[2]) 
m ->m {i {i : (1, 3, 12) 
rF -> VX, VY, VZ : (1, 3, 12) (where 1.0 stands for 360 
degrees) 


RotMatrix_gte() is approximately 2 X faster than RotMatrix() but the result can be different by up to 2/4096. 


RotMatrix() uses the same sincos table. 


Return value 
m 


See also 
RotMatrix...(), RotMatrixC(), RotMatrixX(), RotMatrixY(), RotMatrixYXZ_gte(), RotMatrixZ(), 
RotMatrixZYX_gte() 
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RotMatrixC 

Find a rotation matrix from a rotation angle. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

MATRIX *RotMatrixC( 

SVECTOR “fr, Pointer to rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (output) 

Explanation 


Same as RotMatrix(), but results in a small table and slower speed. 


Return value 
m. 


See also 
RotMatrix...(), RotMatrix_gte(), RotMatrixx(), RotMatrixY(), RotMatrixYXZ_gte(), RotMatrixz0, 
RotMatrixZYX_gte() 
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RotMatrixX 

Find a rotation matrix around the X axis. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

MATRIX *RotMatrixX( 

long r, Rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (output) 

Explanation 


Generates a rotation queue in matrix m as the product of a rotation matrix around the X axis at rotation 
angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 
represents 1.0. 


10 0 
O c -S|*m 
Os c 
However, 
c = cos (r) ‚S= sin (r) 
m ->m [i] ij] : (1, 3, 12) 
r : (1, 3, 12) (where 1.0 stands for 360 


degrees) 


Return value 
m. 


See also 
RotMatrix...(), RotMatrix_gte(), RotMatrixC(, RotMatrixY(), RotMatrixYXZ_gte(), RotMatrixz(), 
RotMatrixZYX_gte() 
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RotMatrixY 

Find a rotation matrix around the Y axis. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

MATRIX *RotMatrixY( 

long r, Rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (input/output) 

Explanation 


Generates a rotation queue in matrix m as the product of a rotation matrix around the Y axis at rotation 
angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 
represents 1.0. 


c 0 -s 
O 1 Oj*m 
s 0 c 
However, 
c = cos (r) ‚S= Sin (r) 
m ->m [i] ij] : (1, 3, 12) 
r : (1, 3, 12) (where 1.0 stands for 360 


degrees) 
Return value 
m 


See also 
RotMatrix...()), RotMatrix_gte(), RotMatrixC(), RotMatrixx(), RotMatrixYXZ_gte(), RotMatrixZ(), 
RotMatrixZYX_gte() 
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RotMatrixYXZ_gte 


Find a rotation matrix from a rotation angle. Approximately 2 X faster than RotMatrixYXZ(). 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

MATRIX *RotMatrixYXZ_gte( 

SVECTOR “fr, Pointer to rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (output) 

Explanation 


Generates a rotation queue in matrix m from the rotation angle ({[0], [1], [2]). A value of 4096 represents a 
rotation angle of 360 degrees, and as a matrix element, 4096 represents 1.0. 


The matrix is found by performing the following multiplication. In GTE's coordinate transformation functions 
(such as RotTransPers()) a vector is multiplied beginning with the rightmost end. This produces rotation 
around the Z axis, Y axis, and X axis. 


cl O si 1 0 0 c2 -s2 0 
O 1 0O/;]*}/0 cO -s0|*Įs2 c2 O 
-s1 0 cl O sO cO 0 0 1 


However, 

cO = cos (r[0]), sO = sin (r[0]) 

c1 = cos (r[1]), s1 = sin (r[1]) 

c2 = cos (r[2]), s2 = sin (r[2]) 

m ->m [i] [j] : (1,3, 12) 

r -> VX, VY, VZ : (1, 3, 12) (where 1.0 stands for 360 
degrees) 


RotMatrixYXZ_gte() is approximately 2 X faster than RotMatrixYXZ() but the result can be different (by 
2/4096 or less). 


RotMatrixYXZ() uses the same lookup table. 


Return value 
m 


See also 
RotMatrix...(), RotMatrix_gte(), RotMatrixC(), RotMatrixxX(), RotMatrixY(), RotMatrixZ(), RotMatrixZYX_gte() 


Run-Time Library Reference CONFIDENTIAL 


Basic Geometry Library Functions 8-123 


RotMatrixZ 

Find a rotation matrix around the Z axis. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

MATRIX *RotMatrixZ( 

long r, Rotation angle input 

MATRIX *m) Pointer to rotation matrix output 

Explanation 


Generates a rotation queue in matrix m as the product of a rotation matrix around the Z axis at rotation 
angle r. A value of 4096 represents a rotation angle of 360 degrees and as a matrix element, 4096 
represents 1.0. 


c -s 0 
s c O|ļ|*m 
Oo O0 1 
However, 
c = cos (r), s =sin (r) 
m ->m [i] ij] : (1, 3, 12) 
r : (1, 3, 12) (where 1.0 stands for 360 


degrees) 
Return value 
m. 


See also 
RotMatrix...(), RotMatrix_gte(), RotMatrixC(), RotMatrixx(), RotMatrixY(), RotMatrixYXZ_gte(), 
RotMatrixZYX_gte() 
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RotMatrixZYX_gte 


Find a rotation matrix around the z, y, and x axis. Approximately 2 X faster than RotMatrixZYXx. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

MATRIX *RotMatrixZYX_gte( 

SVECTOR “fr, Rotation angle (input) 

MATRIX *m) Pointer to rotation matrix (output) 

Explanation 


Generates a rotation queue from the rotation angle (r[0], r[1], [2]) in matrix m. A value of 4096 represents 
360 degrees; and in matrices, 4096 represents 1.0. 


The matrix is obtained by doing the following multiplication. In a coordinate conversion function (such as 
RotTransPers) for GTE, a vector is multiplied beginning with the rightmost end. So, it is rotated around the 
X axis, Y axis, and Z axis. 


c2 -s2 0 c1 O si| |1 O O 


s2 c2 0ļj|*| O 1 O}*}]0 cO -sO 
Oo O0 1 -s1 O ci O sO cO 
However, 
cO = cos (r[0]), sO = sin (r[0]) 
c1 = cos (rji), s1 = sin (r[1]) 
c2 = cos (r[2]), s2 = sin (r[2]) 
m ->m [i] [j] : (1,3, 12) 
r -> VX, VY, VZ : (1, 3, 12) (where 1.0 stands for 360 


degrees) 


RotMatrixZYX_gte() is approximately 2 X faster than RotMatrixZYX() but the results can be different by up to 
2/4096. 


RotMatrixZYX() uses the same lookup table. 


Return value 
m 


See also 
RotMatrix...(), RotMatrix_gte(), RotMatrixC(), RotMatrixx(), RotMatrixY(), RotMatrixYXZ_gte(), RotMatrixZ() 
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RotMeshH 

Perform coordinate transformation and perspective transformation. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

void RotMeshH( 

short *Yheight, Pointer to vertex Y coordinate (input) 

DVECTOR “Vo, Pointer to screen coordinate (output) 

u_short “sz, Pointer to SZ value (output) 

u_short “flag, Pointer to flag (output) 

short Xoffset, short Zoffset, Offsets for X and Z (input) 

short m, short n, Number of vertices (input) 

DVECTOR *base) Pointer to base address 

Explanation 


Performs coordinate transformation and perspective transformation for the number of quadrilateral mesh 
vertices indicated by m x n. 


Vo, sz and flag are not scalar quantities but represent m x n meshes. In other words, this function returns 
various vertex parameters such as DVECTOR vo[n][m], u_short sz[n][m] and u_short flag[n][m]. 


Arguments and internal data format are as follows: 


Yheight : (1, 15, 0) 
Vo -> vX, Vy : (1, 15, 0) 
SZ (0, 16, 0) 
flag : (O, 16, 0) 
Xoffset, Zoffset : (1, 15, 0) 
m,n : (1, 15, 0) 
base > (1, 15, 0) 


The flag must normally be set between bit 27 and bit 12 of the 32-bit flag. 


See also 
RotMeshPrimQ_T(), RotMeshPrimR_...(), RotMeshPrimS_...0 
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RotMeshPrimQ_T 


Two-dimensional mesh. 





Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 
Syntax 
void RotMeshPrimQ_T( 
QMESH “msh, Pointer to mesh model data 
POLY_FT4 “prim, Pointer to GPU packet that should be created 
u_long “ot, Pointer to ordering table 
u_long otlen, Ordering table length 
long dpq, Specifies whether depth cueing will be done (1 = yes, O = no) 
long backc, Specifies whether back clip will be done (1 = yes, O = no) 
SCLIP *sclip, Pointer to screen clip area 
LINE_BUF “line_sxy) Pointer to one line buffer for internal processing 
Explanation 


Perform coordinate conversion, perspective conversion, normal line clip, clipping by screen coordinates (x, 
y, z) and linking to OT of the following two-dimensional mesh (QMESH) data. 








The H direction vertex number must be a multiple of 3 (msh -> lenh = 3 xn). 


1-----2-----3 
| | 
4-----§-----6 
| | | 
7-----8-----9 





Write texture as is (fog gathers, but do not calculate light source). Set the texture coordinates. 


Use the following structures. (The line buffer is secured above 1H + 3 vertices). If scratch pad is used as a 
line buffer, it is faster. 


typedef struct { 
long sminxX; 

long smaxs; 

long sminyY; 

long smaxyY; 

long sminZ; 

long smaxdZ; 

} SCLIP; 


typedef struct { 
long sxy; 

long code; 

} LINE_BUF; 








See also 
RotMeshH(), RotMeshPrimR_...(), RotWMeshPrimS_...() 


Run-Time Library Reference CONFIDENTIAL 


Basic Geometry Library Functions 8-127 


RotMeshPrinfR .... 


The round mesh series of functions. 





Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 
Syntax 
void RotMeshPrimR_...( 
TMESH *msh, Pointer to mesh model data 
POLY_... “prim, Pointer to GPU packet that should be created 
u_long “ot, Pointer to ordering table 
u_long otlen, Ordering table length 
long dq, Specifies whether depth cueing will be done (1 = yes; O = no) 
u_long backc) Specifies whether back clip will be done (1 = yes; O = no) 
Explanation 





Perform coordinate conversion, perspective conversion, and linking to ot of the following round model 
mesh (rmesh) data. 


2:1:3 
ANAN 
ENEN 
1---0---4 


The following round mesh functions are supported in libgte: 


Table 8-3: Libgte Round Mesh Functions 








Function name Type of prim Description 
(2" arg) 
RotMeshPrimR_F3 POLY_F8 Perform flat shading with one vertex color 
(light source calculation). 
RotMeshPrimR_FC3 POLY_F3 Perform complete painting with one vertex 


color (no light source calculation). 
RotMeshPrimR_FCT3 = POLY_FT3 Multiply texture with one vertex color (no light 
source calculation). 
RotMeshPrimR_FT3 POLY_FT3 Multiply the flat-shaded items and the texture 
with one vertex color (light source calculation). 


RotMeshPrimR_G3 POLY_G3 Perform Gouraud shading with vertex color 
(light source calculation). 
RotMeshPrimR_GC3 POLY_G3 Perform complete Gouraud painting with 


vertex color (no light source calculation). 
RotMeshPrimR_GCT3 POLY_GT3 Multiply the Gouraud completely painted 
items and the texture with vertex color (no 
light source calculation). 
RotMeshPrimR_GT3 POLY_GT8 Multiply the Gouraud-shaded items and the 
texture with vertex color (light source 
calculation). 
RotMeshPrimR_T3 POLY_FT3 Write out texture as-is. 








See also 
RotMeshH(), RotMeshPrimQ_T(), RotWeshPrimS_...() 
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RotMeshPrimsS .... 


The strio mesh series of functions. 





Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotMeshPrimS_...( 

TMESH “msh, Pointer to mesh model data 

POLY_... “prim, Pointer to GPU packet that should be created 

u_long “ot, Pointer to ordering table 

u_long otlen, Ordering table length 

long dq, Specifies depth cueing (1 = yes; O = no) 

u_long backc) Specifies back clip (1 = yes; 0 = no) 

Explanation 





Perform coordinate conversion, perspective conversion, and linking to ot of the following strip model mesh 
(rmesh) data. 


1----- 3----- 5 
fy. 2 
i As 4? 
0----- 2----- 4 


The following strip mesh functions are supported in libgte: 


Table 8-4: Libgte Strip Mesh Functions 








Function name Type of prim Description 
(2™ arg) 
RotMeshPrimS_F3 POLY_F8 Perform flat shading with one vertex color 
(light source calc.). 
RotMeshPrimS_FC3 POLY_F3 Perform complete painting with one vertex 


color (no light source calculation). 
RotMeshPrimS_FCT3 = POLY_FT3 Multiply texture with one vertex color (no light 
source calc). 
RotMeshPrimS_FT3 POLY_FT3 Multiply the flat-shaded items and the texture 
with 1 vertex color (light source calculation). 


RotMeshPrimS_G3 POLY_G3 Perform Gouraud shading with vertex color 
(light source calc). 
RotMeshPrimS_GC3 POLY_G3 Perform complete Gouraud painting with 


vertex color (no light source calculation). 
RotMeshPrimS_GCT3 POLY_GT3 Multiply the Gouraud completely painted 
items and the texture with vertex color (no 
light source calculation). 
RotMeshPrimS_GT3 POLY_GT3 Multiply the Gouraud-shaded items and the 
texture with vertex color (light source 
calculation). 
RotMeshPrimS_Ts3 POLY_FT3 Write out texture as-is. 








See also 
RotMeshH(), RotMeshPrimQ_T(), RotMeshPrimR_...() 
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Perform coordinate transformation and perspective transformation for three points, and find an interpolation 


value and outer product for depth cueing. 


Library Header File 
libgte.lib libgte.h 
Syntax 


long RotNclip3( 

SVECTOR *vO, SVECTOR *v1, SVECTOR *v2, 
long *sxy0, long *sxy1, long *sxy2, 

long *p, 

long *otz, 

long *flag) 


Explanation 
A coordinate transformation of three points vO, 


Documentation Date 
12/14/98 


Introduced 
2.X 


Pointer to vectors (input) 

Pointer to coordinates (output) 
Pointer to interpolation value (output) 
Pointer to OTZ value (output) 

Pointer to flag (output) 


v1, v2 is performed using a rotation matrix. Next a 


perspective transformation is performed and three screen coordinates sx0, sx7, and sx2 are returned. An 


interpolation value for depth cueing on v2 to p 
the screen coordinates for v2 to otz. 


vO, v1, V2 -> VX, Vy, VZ : ( 
sxy0, sxy7, Sxy2 zd 
p :( 
otz : ( 
flag : ( 


is also returned. Finally, we also receive 1/4 of the Z value of 


BEREE 


, (1, 15, 0) 
) 


UNa 


VMO O 0 


ooo 


=*= o 





When the return value is negative, SX, SY, etc. 
RotTransPers\(). 


Return value 


are incorrect. When SX and SY are needed, use 


Outer product of (sx0, sy0), (sx7, sy7), (Sx2, sy2) 


See also 
RotNclip3_nom(), RotNclip4() 
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RotNclip3_nom 


Perform coordinate and perspective transformation for three points; get interpolation value and outer 
product for depth cueing. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 
Syntax 


long RotNclip3_nom 
(SVECTOR *vO, SVECTOR *v7, SVECTOR *v2) Pointer to vectors (input) 


Explanation 

After performing coordinate transformation for local coordinate vectors vO, v7, and v2 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates sxO, sy0, 
szO, sx1, sy1, $z1, sx2, sy2, and sz2, the interpolation value p for depth cueing corresponding to v2, and 
an outer product value (opz) for (sxO,syO), (sx1,sy1), and (sx2,sy2) in GTE's internal register. 





VO, v1, V2 -> VX, Vy, VZ : (1, 15, 0) 
sxO, syO, SzO : (1, 15, 0), (1, 15, 0), (0,16,0) 
sx1, sy1, sz1 :(1, 15, O), (1, 15, 0), (0,16,0) 
SX2,Sy2, SZ2 : (1, 15, 0), (1, 15, 0), (0,16,0) 
p : (O, 20, 12 
otz : (0, 32, 0) 
flag : (0, 32, 0) 


The operation result(s) must be retrieved from the GTE (for further information, refer to the Inline Reference 
documentation): 








(sz0,sz1,sz2) is read by macro read_sz_fifo3 

((sxO,syO), (Sx1,sy1), (Sx2,sy2)) is read by macro read_sxsy_fifo3 
p is read by macro read_p 

opz is read by macro read_opz 

flag is returned in register vO. 


Return value 
None. 


See also 
RotNeclip3(), RotNclip4() 
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RotNclip4 
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Perform coordinate transformation and perspective transformation for four points, and find an interpolation 


value and outer product for depth cueing. 


Library Header File Introduced 
libgte.lib libgte.h 2.X 
Syntax 


long RotNclip4( 

SVECTOR “vO, SVECTOR *v7, SVECTOR *v2, SVECTOR *v3, 
long *sxy0, long “sxy7, long *sxy2, long *sxy3, 

long *p, 

long *oiz, 

long *flag) 


Explanation 


Documentation Date 
12/14/98 


Pointer to vectors (input) 

Pointer to coordinates (output) 
Pointer to interpolation value (output) 
Pointer to OTZ value (output) 

Pointer to flag (output) 


A coordinate transformation of four points vO, v7, v2, v3 is performed using a rotation matrix. Next a 
perspective transformation is performed and three screen coordinates sx0, sx1, sx2, and sx3 are returned. 
An interpolation value for depth cueing on v2 to p is also returned. Finally, we also receive 1/4 of the Z value 


of the screen coordinates for v2 to otz. 


vO, v1, V2, V3 -> VX, Vy, VZ 


rea 


:(1, 15, O 
SXy0, Sxy7, Sxy2, Sxy3 : (1, 15, 0), (1, 15, 0) 
p : (0, 20, 12) 
otz : (0, 32, 0) 
flag : (0, 32, 0) 


When the return value is negative, SX, SY, etc. are incorrect. When SX and SY are required, use 


RotTransPers4(). 


Return Value 
Outer product of (sxO, sy0), (Sx1, sy1), (Sx2, sy2) 


See also 
RotNclip3() 
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RotPMD._... 

The independent vertex PMD data series of functions. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotPMD....( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int backc) Normal line clipping ON/OFF (0: ON) 

Explanation 


These functions perform coordinate transformations and perspective transformations on all three and four- 
side polygons included in the independent vertex PRIMITIVE Gp, then complete the GPU packet and link it 
to OT. 


Only polygons with an SZ value within the range [h/2, 2416] may be linked. 
The following independent vertex PMD functions are supported in libgte: 


Table 8-5: Libgte Independent Vertex PMD Functions 








Function Name Description 

RotPMD_F8 Flat triangle 

RotPMD_F4 Flat quadrilateral 
RotPMD_FT3 Flat textured triangle 
RotPMD_FT4 Flat textured quadrilateral 
RotPMD_G3 Gouraud triangle 

RotPMD_G4 Gouraud quadrilateral 
RotPMD_GT3 Gouraud textured triangle 
RotPMD_GT4 Gouraud textured quadrilateral 





An error may occur when placing model data (PRIMITIVEGp) on the scratch pad. 


See also 
RotPMD_SV_...(), RotRMD_...(), RotRMD_SV_...(), RotSMD_...(), RotSMD_SV_...() 
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RotPMD_SV_.... 


The shared vertex PMD data series of functions. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotPMD_SV_...( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

long *va, Pointer to starting address of VERTEX Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int backc) Normal line clipping ON/OFF (0: ON) 

Explanation 





These functions perform coordinate and perspective transformations on all three- and four-sided polygons 
included in the shared vertex PRIMITIVE Gp, then complete the GPU packet and link it to OT. 


Only polygons with an SZ value within the range [h/2, 2416] may be linked. 
The following shared vertex PMD functions are supported: 


Table 8-6: Libgte Independent Vertex PMD Functions 








Function Name Description 

RotPMD_SV_F3 Flat triangle 

RotPMD_SV_F4 Flat quadrilateral 
RotPMD_SV_FT3 Flat textured triangle 
RotPMD_SV_FT4 Flat textured quadrilateral 
RotPMD_SV_G3 Gouraud triangle 
RotPMD_SV_G4 Gouraud quadrilateral 
RotPMD_SV_GT3 Gouraud textured triangle 
RotPMD_SV_GT4 Gouraud textured quadrilateral 





See also 
RotPMD_...(), RotRMD_...(), RotRMD_SV_...(), RotSMD_...(), RotSMD_SV_...() 
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RotRMD.... 

The independent vertex RMD data series of functions. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotRMD_...( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int sclio, Screen clio ON/OFF (ON=1) 

int Aclip, H direction clip ((0,hclip]=display) 

int vclip, V direction clip ([0,vclip]=display) 

int Ncliomode) Near Z clip mode (O=0,SCRZ/2=1) 

Explanation 


These functions perform coordinate transformations and perspective transformations on all three and four- 
sided polygons included in independent vertex type PRIMITIVE Gp, then create GPU packets and link them 
to OT. 


If sclio = O, all polygons are displayed. 


If sclip = 1, only polygons having at least one vertex that is included in the square ([0,hclip],[O,vclip]) are 
displayed. 


If ncliomode = 0, polygons are far and near clipped by sz=[0,2416]. 

If nclipmode = 1, polygons are far and near clipped by sz=[h,2“16] (h=distance of eye to screen). 
No polygons are backface clipped. 

The following independent vertex RMD functions are supported: 


Table 8-7: Libgte Independent Vertex RMD Functions 








Function Name Description 

RotRMD_F3 Flat triangle 

RotRMD_F4 Flat quadrilateral 
RotRMD_FT3 Flat textured triangle 
RotRMD_FT4 Flat textured quadrilateral 
RotRMD_G3 Gouraud triangle 

RotRMD_G4 Gouraud quadrilateral 
RotRMD_GT3 Gouraud textured triangle 
RotRMD_GT4 Gouraud textured quadrilateral 





An error may occur when placing model data (PRIMITIVEGp) on the scratch pad. 


See also 
RotPMD_...(),RotPMD_SV_...(), RotRMD_SV_...(), RotSMD_...(), RotSMD_SV_...() 
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RotRMD_SV.... 


The shared vertex RMD data series of functions. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotRMD_SV_...( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int sclio, Screen clio ON/OFF (ON=1) 

int Aclip, H direction clip ((0,hclip]=display) 

int vclip, V direction clip ([0,vclip]=display) 

int Ncliomode) Near Z clip mode (O=0,SCRZ/2=1) 

Explanation 





These functions perform coordinate and perspective transformations on all three and four-sided polygons 
included in shared vertex type PRIMITIVE Gp, then create GPU packets and link them to OT. 


If sclio = O, all polygons are displayed. 


If sclip = 1, only polygons having at least one vertex that is included in the square ([0,)clip],[O,vclip]) are 
displayed. 


If ncliomode = 0, polygons are far&near clipped by sz=[0,2416]. 

If ncliomode = 1, polygons are far&near clipped by sz=[h,2416] (h=distance of eye to screen). 
No polygons are backface clipped. 

The following shared vertex RMD functions are supported: 


Table 8-8: Libgte Shared Vertex RMD Functions 








Function Name Description 

RotRMD_SV_F3 Flat triangle 

RotRMD_SV_F4 Flat quadrilateral 
RotRMD_SV_FT3 Flat textured triangle 
RotRMD_SV_FT4 Flat textured quadrilateral 
RotRMD_SV_G3 Gouraud triangle 
RotRMD_SV_G4 Gouraud quadrilateral 
RotRMD_SV_GTS3 Gouraud textured triangle 
RotRMD_SV_GT4 Gouraud textured quadrilateral 





See also 
RotPMD_...(), RotPMD_SV_...(, RotRMD_...(), RotSMD_...(), RotSMD_SV_...() 
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RotSMbD..... 

The independent vertex SMD data series of functions. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotSMD_...( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int sclio, Screen clio ON/OFF (ON=1) 

int Aclip, H direction clip ((0,hclip]=display) 

int vclip, V direction clip ([0,vclip]=display) 

int Ncliomode) Near Z clip mode (O=0,SCRZ/2=1) 

Explanation 


These functions perform coordinate transformations and perspective transformations on all three and four- 
sided polygons included in independent vertex type PRIMITIVE Gp, then create GPU packets, and link 
them to OT. 


If sclio = O, all polygons are displayed. 


If sclio = 1, only polygons with at least one vertex that is included in the square ([0,hclio],[0,vclio]) are 
displayed. 


If nclipmode = O, polygons are far&near clipped by sz=[0,216]. 





If nclipmode = 1, polygons are far&near clipped by sz=[h,2416] (h=distance of eye to screeen). 
All polygons are backface clipped. 
The following independent vertex SMD functions are supported in libgte: 


Table 8-9: Libgte Independent Vertex SMD Functions 








Function Name Description 

RotSMD_F8 Flat triangle 

RotSMD_F4 Flat quadrilateral 
RotSMD_FTS3 Flat textured triangle 
RotSMD_FT4 Flat textured quadrilateral 
RotSMD_G3 Gouraud triangle 

RotSMD_G4 Gouraud quadrilateral 
RotSMD_GT3 Gouraud textured triangle 
RotSMD_GT4 Gouraud textured quadrilateral 





An error may occur when placing model data (PRIMITIVEGp) on the scratch pad. 


See also 
RotPMD_...(, RotPMD_SV_...(), ROtRMD_...(), RotRMD_SV_...(), RotSMD_SV_...() 
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RotSMD_SV.... 


The shared vertex SMD data series of functions. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 

Syntax 

void RotSMD_SV_...( 

long *pa, Pointer to starting address of PRIMITIVE Gp 

u_long “ot, Pointer to starting address of OT 

int otlen, Length of OT (number of bits) 

int id, Double buffer ID 

int sclio, Screen clio ON/OFF (ON=1) 

int Aclip, H direction clip ((0,hclip]=display) 

int vclip, V direction clip ([0,vclip]=display) 

int Ncliomode) Near Z clip mode (O=0,SCRZ/2=1) 

Explanation 


These functions perform coordinate transformations and perspective transformations on all three and four- 
sided polygons included in shared vertex type PRIMITIVE Gp, then create GPU packets, and link them to 
OT. 


If sclio = O, all polygons are displayed. 


If sclio = 1, only polygons with at least one vertex that is included in the square ([0,hclio],[0,vclio]) are 
displayed. 


If nclipmode = O, polygons are far&near clipped by sz=[0,216]. 





If nclipmode = 1, polygons are far&near clipped by sz=[h,2416] (h=distance of eye to screeen). 
All polygons are backface clipped. 
The following shared vertex SMD functions are supported in libgte: 


Table 8-10: Libgte Shared Vertex SMD Functions 








Function Name Description 

RotSMD_SV_F3 Flat triangle 

RotSMD_SV_F4 Flat quadrilateral 
RotSMD_SV_FT3 Flat textured triangle 
RotSMD_SV_FT4 Flat textured quadrilateral 
RotSMD_SV_G3 Gouraud triangle 
RotSMD_SV_G4 Gouraud quadrilateral 
RotSMD_SV_GT3 Gouraud textured triangle 
RotSMD_SV_GT4 Gouraud textured quadrilateral 





See also 
RotPMD_...(), RotPMD_SV_...(, RotRMD_...(), RotRMD_SV_...(), RotSMD_...() 
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RotTrans 
Perform coordinate transformation using a rotation matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 

void RotTrans( 

SVECTOR “vO, Pointer to vector (input) 
VECTOR *v1, Pointer to vector (output) 
long *flag) Pointer to flag 


Explanation 
Calculates v7 = RTM x vo. 


VO -> VX, VY, VZ : ( 

V1 -> VX, W, VZ : (1, 31,0 
flag :( O 
See also 


RotTrans_nom(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSV(), TransRot_32() 
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RotTrans_nom 
Perform coordinate transformation using a rotation matrix. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 


void RotTrans_nom ( 
SVECTOR *v0) Pointer to vector (input) 


Explanation 

Calculates v7 = RTM x vo. 
VO -> VX, VY, VZ Ef 

V1 -> VX, VY, VZ : (1, 31, 0) 
flag :( 0) 





The operation result(s) must be retrieved from the GTE. (For further information, refer to the Inline Reference 
documentation.) 


e  (v1->vx,v1->vy,v1->vz) is read by macro read_mt 
e flag is read by macro read_flag. 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSV() 
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RotTransPers 

Perform coordinate and perspective transformation for one vertex. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotTransPers( 

SVECTOR *Vv0, Pointer to vertex coordinate vector (input) 

long *sxy, Pointer to screen coordinates 

long *p, Pointer to interpolated value 

long *flag) Pointer to flag 

Explanation 


After converting the coordinate vector vO with a rotation matrix, the function performs perspective 
transformation, and returns screen coordinates sx, sy. It also returns an interpolated value for depth cueing 


in p. 

VO -> VX, VY, VZ > (1, 15, O) 

sxy : (1, 15, 0), (1, 15, 0) 
p : (O, 20, 12) 

flag : (0, 32, 0) 


Return value 
1/4 of the screen coordinate Z component sz. 


See also 
RotTrans(), RotTransPers_nom(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSV(), TransRotPers() 
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RotTransPers_ nom 


Perform coordinate and perspective transformation for one vertex. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

long RotTransPers_nom( 

SVECTOR *v0) Pointer to vertex coordinate vector (input) 

Explanation 


After converting the coordinate vector vO with a rotation matrix, the function performs perspective 
transformation, and stores screen coordinates sx, sy, sz and the interpolated value p for depth cueing in 
the GTE internal register. 


The argument and internal data format is as follows: 


vO -> VX, VY, VZ > (1, 15, O) 
SX > (1, 15, 0) 
Sy : (1, 15, 0) 
SZ : (0, 16, 0) 
p : (0,20, 12) 
flag : (0, 32, 0) 


sz is read by macro read_sz2, (sx,sy) is read by macro read_sxsy2, p is read by macro read_p and flag is 
read by macro read_flag. 


The operation result(s) must be retrieved from the GTE. 


For further information, refer to the Inline Reference documentation. 


Return value 
None. 


See also 
RotTrans(), RotTransPers_nom(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSvV() 
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RotTransPerss 

Perform coordinate and perspective transformation of three vertices. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


long RotTransPers3( 
SVECTOR *vO, SVECTOR *v1, SVECTOR *v2, Pointer to vertex coordinate vectors 


long *sxy0, long *sxy1, long *sxy2, Pointer to screen coordinates 

long *p, Pointer to depth cueing interpolated value 
long *flag) Pointer to flag 

Explanation 


Transforms the three coordinate vectors vO, v7, and v2 using a rotation matrix, performs perspective 
transformation, and returns three screen coordinates sxyO, sxy7, and sxy2. It also returns to p an 
interpolated value for depth cueing corresponding to v2. 





vO, v1, V2 -> VX, VY, VZ > (1, 15, 0) 

sxy0, sxy7, SXy2 > (1, 15, O), (1, 15, 0) 
p : (0, 20, 12) 

flag : (0, 32, 0) 


Return value 
1/4 of the screen coordinate Z component sz corresponding to v2. 


See also 


RotTrans(), RotTransPers(), RotTransPers3_nom(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSV(), TransRotPerss\() 
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RotTransPers3_nom 


Perform coordinate and perspective transformation of three vertices. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 
Syntax 


long RotTransPers3_nom( 
SVECTOR *vO, SVECTOR *v7, SVECTOR “*v2) Pointers to vertex coordinate vectors 


Explanation 

After performing coordinate transformation for local coordinate vectors vO, v1, and v2 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates sxO, syO, 
szO, sx1, sy1, sz1, Sx2, sy2, sz2 and the interpolation value p for depth cueing corresponding to v2 in 
GTE's internal register. 





The argument and internal data format is as follows: 


VO, v1, V2 -> VX, Vy, VZ : (1, 15, 0) 

sx0O, syO, SzO : (1, 15, 0), (O, 16, O) 
Sx1, sy1, sz1 : (1, 15, 0), (O, 16, O) 
SX2, SY2, SZ2 : (1, 15, 0), (O, 16, O) 
p : (O, 20, 12) 

flag : (0, 32, 0) 


(sz0,sz1,sz2) is read by macro read_sz_fifo3, ((sxO,syO), (sx1,sy1),(Sx2,sy2) is read by macro 
read_sxsy_fifo3, p is read by macro read_p and flag is read by macro read_flag. 


The operation result(s) must be retrieved from the GTE. 


For further information, refer to the Inline Reference documentation. 





Return value 
None. 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSv() 
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RotTransPers3N 
Perform coordinate and perspective transformation for multiple triangles 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 
Syntax 
void RotTransPers3N( 
SVECTOR “vO, Pointer to vertex coordinate vector (input) 
DVECTOR *v7, Pointer to vertex coordinate vector (output) 
u_short “sz, Pointer to SZ value (output) 
u_short “flag, Pointer to flag (output) 
long n) Number of triangles to process (number of input vertices/3) 
Explanation 


Executes RotTransPers3() for the number of triangles specified by n. It transforms 3 vertices at a time and 
stores 3 screen coordinates, an sz value and a flag value. 


vO points to an array of SVECTOR that must be 3 times n in length. v7 points to an array of DVECTOR 
(screen coordinates) that must be 3 times n in length. sz and flag point to arrays of shorts that must each 
be n in length. 


Arguments and internal data formats are as follows: 


VO -> VX, Vy, VZ : (1, 15, 0) 
v1 -> VX, Vy : (1, 15, 0) 
SZ : (0, 16, 0) 
flag : (0, 16, 0) 


Since the flag is a short, it has been right-shifted 12 places, so the information returned is that normally 
found between bits 27 and 12 in the 32-bit flag. 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers4(), RotTransPersN(), RotTransSV() 
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RotTransPers4 

Perform coordinate and perspective transformation for 4 vertices. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 


long RotTransPers4( 

SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vectors (input) 
SVECTOR ‘v3, 

long *sxy0, long *sxy1, long *sxy2, long *sxy3, Pointer to screen coordinates 


long *p, Pointer to interpolated value for depth cueing 
long *flag) Pointer to flag 
Explanation 


After transforming the four coordinate vectors vO, v7, v2, and v3 using a rotation matrix, the function 
performs perspective transformation, and returns four screen coordinates sxy0, sxy7, sxy2, and sxy3. It 
also returns an interpolation value for depth cueing to p corresponding to v3. The argument format is as 
follows: 


vO, V1, V2, V3 -> VX, vy, VZ > (1, 15, 0) 

Sxy0, SXy1, Sxy2, Sxy3 : (1, 15, 0), (1,15,0) 
p : (0, 20, 12) 

flag : (0, 16, 0) 


Return value 
1/4 of the Z component sz of the screen coordinates corresponding to v3. 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4_nom(), RotTransPersN(), 
RotTransSvV() 
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RotTransPers4 nom 


Perform coordinate and perspective transformation for 4 vertices. Results obtained through GTE. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 
Syntax 


long RotTransPers4_nom( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, SVECTOR *v3) Pointer to vectors (input) 


Explanation 


After performing coordinate transformation for local coordinate vectors vO, v1, v2 and v3 using a rotation 
matrix, this function performs perspective transformation and stores three screen coordinates (SzO), 
(sx1,sy1,8z1), (Sx2,sy2,SZ2),(Sx8,Sy3,Sz3), and the interpolation value p for depth cueing corresponding to 
v3 in GTE's internal register. 


The argument and internal data format is as follows: 


VO,V1,V2-> VX, Vy, V : (1, 15, 0) 

sx0,sy0,szO : (1,15,0)}, (1,15,0), (0,16,0) 
sx1,sy1,sz1 : (1,15,0), (1,15,0), (0,16,0) 
Sx2,Sy2,SZ2 (1,15,0), (1,15,0), (0,16,0) 
Sx3,Sy3,8z3 (1,15,0), (1,15,0), (0,16,0) 
p : (0,20,12) 

flag : (0,32,0) 


(sz0,sz1,Sz2,Sz3) is read by macro read_sz_fifo4, ((Sx1,sy1),(Sx2,Ssy2),(Sx3,sy3) is read by macro 
read_sxsy_fifo3 and p is read by macro read_p. (sxO,sy0) is returned in register v1. flag is returned in 
register vO. 


The operation result(s) must be retrieved from the GTE. 





For further information, refer to the Inline Reference documentation. 


Return value 
flag 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN(), 
RotTransSv() 
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RotTransPersN 

Perform coordinate and perspective transformation. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

void RotTransPersN( 

SVECTOR “vO, Pointer to vertex coordinate vector (input) 

DVECTOR *v7, Pointer to vertex coordinate vector (output) 

u_short “sz, Pointer to SZ value (output) 

u_short “p, Pointer to interpolation value (output) 

u_short “flag, Pointer to flag (output) 

long n) Number of vertices (output) 

Explanation 





Executes RotTransPers() for the number of vertices specified by n. 


The arguments and internal data formats are as follows: 


VO -> VX, Vy, VZ : (1, 15, O) 
v1 -> vx, Vy : (1, 15, 0) 
SZ : (O, 16, 0) 
flag : (0, 16, 0) 


The flag must normally be set between bits 27 and 12 of the 32-bit flag. 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransSV() 
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RotTransSV 


Perform coordinate translation with rotation matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.2 12/14/98 


Syntax 

void RotTransSV( 

SVECTOR “*VvO, Pointer to input: vector 
SVECTOR “v7, Pointer to output: vector 
long *flag) Pointer to output: flag 
Explanation 

RotTrans output short vector edition 


v1 = RITM x vO 


VO>VX,VY,VY : ( 
V1->VX,VY,VZ : ( 
flag a 


See also 
RotTrans(), RotTransPers(), RotTransPers3(), RotTransPers3N(), RotTransPers4(), RotTransPersN() 
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rsin 
Sine. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.0 12/14/98 


Syntax 
int rsin( 
int a) Angle (in PlayStation format) 


Explanation 
Finds the sine function of the angle (in PlayStation format) (4096 = 360 degrees = 2pai) using fixed-point 
math (where 4096=1.0). 


a : PlayStation format (4096 = 360 degrees = 2pai) 


Compared to csin(), rsin( is faster and takes up more space. 


Return value 
sin (a) : (1, 19, 12) 


See also 
csin(), rcos(), ratan2() 
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ScaleMatrix 
Scale a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

MATRIX *ScaleMatrix( 

MATRIX *m, Pointer to matrix (output) 

VECTOR *v) Pointer to scale vector (input) 

Explanation 

Scales m by v. The components of v are fixed point decimals in which 1.0 represents 4096. 


If: 





[a00 a01 a02 
m= |{al0 ali a12ļ|, v= [sx, sy sz] 
[a20 a21 a22 
Then: 
[a00xsx a0ixsy a02xsz 
mz=}alOxsx alixsy al2xsz 
[|a2z0xsx a21xsy a22xsz 
m ->m [i] [j] : (1, 19, 12) 
V -> VX, Vy, VZ : (1, 19, 12) 
Return value 
m 
See also 
ScaleMatrixL() 
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ScaleMatrixL 


Scale a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 

MATRIX *ScaleMatrixL( 

MATRIX *m, Pointer to matrix (output) 

VECTOR “v) Pointer to scale vector (input) 

Explanation 

Scales matrix m by v. The elements of v are fixed point numbers in which 4096 represents a value of 1.0. 


If: 


a00 a01 a02 
m=]|al0 all al2}, v= [sx sy sz] 
a20 a21 a22 
Then: 
aOOxsx a01xsx a02xsx 
ms=|alOxsy alixsy al2xsy 
a20xsz a21xsz a22xsz 
m ->m [i] [j] : (1, 19, 12) 
V -> VX, VY, VZ : (1, 19, 12) 
Return value 
m 
See also 
ScaleMatrix() 
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SetBackColor 


Set back color vector. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 

void SetBackColor( 

long rbk, long gbk, long bbk) Colors (input) 

Explanation 

Sets the back color vector to (rbk, gbk, bbk). Color values are in the range O to 255. 


(rok, gbk, bbk) : (0, 32, 0) 





See also 
SetFarColor() 
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SetColorMatrix 


Set a local color matrix. 


Library Header File Introduced Documentation Date 
libgte. lib liogte.h 2.X 12/14/98 


Syntax 


void SetColorMatrix( 
MATRIX *m) 


Arguments 

m: Pointer to matrix (input) 
Explanation 

Sets a local color matrix specified by m. 
m ->m [i] fi]: (1, 3, 12) 
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SetFarColor 


Set far color vectors. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 
void SetFarColor( 
long rfc, long gfc, long bfc) Color values (input) 


Explanation 
Sets the far color vector to (rfc, gfc, bfc). Color values are in the range O to 255. 


(rfc, gfc, bfc) : (0, 32, O) 


See also 
SetBackColor() 
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SetFogFar 


Set a fog parameter. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 

void SetFogFar( 

long a, Z value (0 — 65536) 

long h) Distance between visual point and screen 

Explanation 

a defines the Z value at which fog is 100%. A Z value of 0.2 * a will automatically make fog 0%. 
a: (0, 82, 0) 

h : (O, 82, 0) 

See also 

SetFogNear(), SetFogNearFar() 
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SetFogNear 

Set a fog parameter. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void SetFogNear( 

long a, Z value (0 — 65536 x .2) 

long h) Distance between visual point and screen 

Explanation 

a defines the Z value at which fog is 0%. A Z value of 5 x a will automatically make fog 100%. 

a : (0, 32, 0) 

h : (0, 32, 0) 

See also 


SetFogFar(), SetFogNearFar() 
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SetFogNearFar 

Set the fog parameters. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.2 12/14/98 

Syntax 

void SetFogNearFar( 

long a, Z value with fog at 0% (0 - 65536) 

long b, Z value with fog at 100% (0 - 65536) 

long h) Distance between visual point and screen 

Explanation 

a defines the Z value with fog at 0%. b defines the Z value with fog at 100%. 

(b-a ) > = 100. 


The actual value set to the DQA and DQB GTE register is calculated using the method below: 
K=-a*b/(b-a) 

c =(b << 12) /(b - a) 

DQA = (K/h) << 8 


DQB =c << 12 

However, since the DQA register is 16 bit, a limit of 16 bits is set. 
a : (0, 32, 0) 

b : (0, 32, 0) 

h : (0, 32, 0) 

See also 


SetFogFar(), SetFogNear() 
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SetGeomOffset 


Set offset values. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 


void SetGeomOffset( 
long ofx, long ofy) Offset input values 


Explanation 
Sets the offset values (Of, ofy). 


ofx, ofy : (1, 31, O) 


See also 
SetGeomScreen() 
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SetGeomScreen 
Set the projection. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 


void SetGeomScreen( 
long h) Distance 


Explanation 
Sets the distance h (projection) from a visual point (the eye) to the screen. 


h : (0, 32, 0) 


See also 
SetGeomOffset() 
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SetLightMatrix 


Set a local light matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 


void SetLightMatrix( 
MATRIX *m) Pointer to matrix (input) 


Explanation 
Sets a local light matrix specified by m. 


m ->m [i] fl: (, 3, 12) 
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SetMulMatrix 

Multiply two matrices and set one rotation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 

Syntax 


MATRIX *SetMulMatrix( 
MATRIX *m0, MATRIX *m7) Pointer to input matrices 


Explanation 
Multiplies two matrices and stores that value in one constant rotation matrix. 


m0d,m1 ->m [i] [i]: (1, 3, 12) 


Return value 
Returns m0. 


See also 
SetMulRotMatrix() 
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SetMulRotMatrix 

Multiply constant rotation matrix by a matrix and set one constant rotation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.6 12/14/98 

Syntax 

MATRIX *SetMulRotMatrix( 

MATRIX *m0) Pointer to input matrix 

Explanation 


Multiplies constant rotation matrix and a matrix and stores that value in one constant rotation matrix. 


m0 ->m [i] [] : (1, 3, 12) 


Return value 
mO 


See also 
SetMulMatrix() 
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SetRGBcd 

Set primary color vector and GPU code. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void SetRGBcd( 

CVECTOR *v) Pointer to color vector and GPU code input. 

Explanation 


Sets the primary color vector and GPU code v. 
v -> r, g, b, cd: (O, 8, 0) 
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SetRotMatrix 

Set a constant rotation matrix. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void SetRotMatrix( 

MATRIX *m) Pointer to matrix (input) 

Explanation 


Sets a 3x3 matrix m as a constant rotation matrix. 


m ->m [i] j]: (1, 3, 12) 


See also 
SetTransMatrix() 
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SetTransMatrix 

Set a constant parallel transfer vector. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 

Syntax 

void SetTransMatrix( 

MATRIX *m) Pointer to matrix (input) 

Explanation 


Sets a constant parallel transfer vector specified by m. 
m ->t [i]: (1, 31, 0) 


See also 
SetRotMatrix() 
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Square0 

Square a vector. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void Square0( 

VECTOR “vO, Pointer to vector (L1, L2, L8) (input) 

VECTOR *v7) Pointer to vector (L142, L242, L842) (output) 

Explanation 

Returns a vector, obtained by squaring each term of the vector vO, to v7. 

VO -> VX, VY, VZ : (1, 31, 0) 

V1 -> VX, VY, VZ : (1, 31, 0) 

Return value 

Returns v1 

See also 


Square1 2(), SquareSLO(), SquareSL12(), SquareSSO(), SquareSS1 2() 
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Square12 
Square a vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 

void Square1 2( 

VECTOR *VO, Pointer to vector (L1, L2, L8) (input) 
VECTOR *v1) Pointer to vector (L142, L242, L842) (output) 


Explanation 


Returns a vector, obtained by dividing the square of each term of the vector vO by 4096, to v7. 





vO -> VX, Vy, VZ : (1, 19, 12) 
v1 -> VX, Wy, VZ : (1, 19, 12) 


Return value 
Returns v1 


See also 
Square0(), SquareSLO(), SquareSL12(), SquareSSO(), SquareSS120) 
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SquareRoot0 
Square root. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 
long SquareRoot0( 
long a) Value 


Explanation 
Returns the square root of a value a. 


a: (0, 32, 0) 


Return value 
Returns the square root of a 


See also 
csqrt(), InvSquareRoot(), SquareRoot12() 
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SquareRoot12 
Square root. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 


long SquareRoot1 2( 
long a) Value 


Explanation 
Returns the square root of a value a, which has (0, 20, 12) format, in (O, 20, 12) format. 


a : (0, 20, 12) 


Return value 
Square root of a. 


See also 
csqrt(), InvSquareRoot() 
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SquareSLO 

Square a short vector. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.0 12/14/98 

Syntax 

VECTOR *SquareSL0( 

SVECTOR “vO, Input: short vector (L1, L2, L3) 

VECTOR *v7) Output: vector (L142, L242, L342) 

Explanation 

Returns a vector, obtained by squaring each term of the short vector vO, to v7. 

vO -> Vx, vy, VZ : (1, 15, 0) 

v1 -> Vx, wy, VZ : (1, 31, 0) 


Return value 
v1 


See also 
SquareO(), Square12(), SquareSL12(), SquareSSO(), SquareSS12() 
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SquareSL12 


Square a short vector. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.0 12/14/98 
Syntax 


VECTOR *SquareSL12( 
SVECTOR “vO, Input: short vector (L1, L2, L3) 
VECTOR *v7) Output: vector (L142, L242, L342) 


Explanation 
Returns a vector divided by 4096, obtained by squaring each term of the short vector vO, to v7. 


VO -> VX, VY, VZ : (1, 3,12) 
V1 -> VX, VY, VZ : (1,19,12) 


Return value 
v1 


See also 
SquareO(), Square12(), SquareSLO(), SquareSSO(), SquareSS 1 2() 
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SquareSSO 


Square a short vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.0 12/14/98 
Syntax 


SVECTOR *SquareSS0( 
SVECTOR “vO, Input: short vector (L1, L2, L3) 
SVECTOR “*v7) Output: vector (L142, L242, L342) 


Explanation 
Returns a short vector, obtained by squaring each term of the short vector vO, to v7. 


VO -> VX,VY,VZ : (1,15, 0) 
v1 -> VX, VY, VZ : (1,15, 0) 


Return value 
v1 


See also 
SquareO(), Square12(), SquareSLO(), SquareSL12(), SquareSS12() 
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SquareS$12 

Square a short vector. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 4.0 12/14/98 

Syntax 

SVECTOR *SquareSS1 2( 

SVECTOR “vO, Input: short vector (L1, L2, L3) 

SVECTOR “*v7) Output: vector (L142, L242, L342) 

Explanation 

Returns a short vector divided by 4096, obtained by squaring each term of the short vector vO, to v7. 

vO -> Vx, vy, VZ : (1, 3, 12) 

v1 -> vX, Vy, VZ : (1, 3, 12) 

Return value 

v1. 

See also 


Square0(), Square12(), SquareSLO(), SquareSL12(), SquareSSO() 
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SubPol3 
Subdivide a triangle. 
Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.x 12/14/98 
Syntax 
void SubPol3( 
POLS *p, Pointer to a 3-vertex polygon 
SPOL “sp, Pointer to subdivision vertex array 
int ndiv) Number after subdivision 
0: None 
1: 2x2 
2: 4x4 
Explanation 


Subdivides a three-sided polygon p by the number 2**ndiv, and returns the subdivision vertex coordinates, 
texture coordinates, and RGB to a triangle in an array indicated by sp. 


Figure 8-1 Triangle subdivision 


p[0] p[1] sp[0] sp[1] spl2] 
Ze sp[3] sp[4] 

p[2] sp[6] 

p -> SXy : (1, 15, 0}, (1, 15, 0) 

p -> SZ : (0, 16, 0) 

p -> uv {14 15, 0), (1, 15, O) 

p -> rgb : (0, 8, 0), (O, 8, 0), (O, 8, 0) 

p -> code : (0, 32, 0) 

Sp -> xy : (1, 15, 0), (1, 15, 0) 

Sp -> uv : (1, 15, 0), (1, 15, 0) 

sp -> rgb : (0, 8, 0), (0, 8, 0), (0, 8, 0) 

See also 

SubPol4() 
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SubPol4 

Subdivide a quadrilateral. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

void SubPol4( 

POL4 *p, Pointer to a 4-vertex polygon 

SPOL “sp, Pointer to subdivision vertex array 

int ndiv) Number after subdivision 


O: None, 1: 2x2, 2: 4x4 


Explanation 


Subdivides a four-sided polygon p by the number 2**ndiv, and returns the subdivision vertex coordinates, 
texture coordinates, and RGB to an array indicated by sp. 


Figure 8-2 Quadrilateral subdivision 


p[0] p[t] sp[0] sp[1] sp[2] 





p[2] p[3] sp[6] sp[7] sp[8] 


p -> sxy (1, 15, 0, (1, 15,0) 

p -> SZ (0, 16, 0) 

p -> uv : (1, 15, 0), (1, 15, 0) 

p -> rgb : (0, 8, 0), (O, 8, O), (0, 8, O) 
p -> code : (0, 32, O) 

Sp -> Xy (1, 15, 0, (1, 15,0) 

Sp -> uv (1, 15, O), (1, 15, 0) 

sp -> rgb (0, 8, 0), (0, 8, O), (0, 8, O) 
See also 

SubPol8() 
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TransMatrix 

Set the amount of parallel transfer. 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

MATRIX *TransMatrix( 

MATRIX *m, Pointer to matrix (output) 

VECTOR *v) Pointer to transfer vector (input) 

Explanation 

Gives an amount of parallel transfer expressed by v to the matrix m. 

m ->m [i] [i] {13,13 

m ->t [i] (13140 

V -> VX, VY, VZ : (1, 31, 0) 

Return value 

m. 

See also 

TransposeMatrix() 
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TransposeMatrix 
Transpose a matrix. 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 2.X 12/14/98 


Syntax 

MATRIX *TransposeMatrix( 

MATRIX *m0, Pointer to matrix (input) 
MATRIX *m1) Pointer to matrix (output) 
Explanation 

Transposes matrix m0 into m7. 

mO ->m {ij [j] io; 12 
m1 ->m [i] [j] (1,3,12 
Return value 

Returns m1. 


See also 
TransMatrix() 
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TransRotPers 

Inversely perform rotation parallel move of RotTransPers(). 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 

Syntax 

long TransRotPers( 

SVECTOR “*VvO, Pointer to vertex coordinate vector (input) 

long *sxy, Pointer to screen coordinate value (output) 

long *p, Pointer to interpolation value for depth cueing(output) 

long *flag) Pointer to flag (output) 

Explanation 


Rotates after performing a parallel move of the coordinate vector vO with the rotation matrix. 


Performs a perspective conversion and then a coordinate conversion and returns screen coordinates sx, 
Sy. 


Also, returns the interpolation value for depth cueing to p. 


VO -> VX, VY, VZ : (1, 15, 0) 
SXY (1, 15, O), (1, 15, 0) 
p : (O, 20, 12) 
flag : (0, 32, 0) 


Return value 
1/4 of the screen coordinate Z component sz corresponding to v2. 


See also 
RotTransPers(), TransRotPers3(), TransRot_32() 
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TransRotPers3 

Inversely perform rotation parallel move of RotTransPers3\(). 
Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.2 12/14/98 

Syntax 


long TransRotPers3( 
SVECTOR *vO, SVECTOR *v7, SVECTOR *v2, Pointer to vertex coordinate vector (input) 


long *sxy0, long “sxy7, long *sxy2, Pointer to screen coordinate value (output) 

long *p, Pointer to interpolation value for depth cueing (output) 
long *flag) Pointer to flag (output) 

Explanation 


Rotates after performing a parallel move of the three coordinate vectors vO,v7,v2 with the rotation matrix. 
Performs a perspective conversion and then a coordinate conversion and returns the three screen 
coordinates sxyO, sxy7, and sxy2. 





Also, returns the interpolation value for depth cueing compatible with v2 to p. 


Also, returns the screen coordinate Z item sz 1/4 compatible with v2 as the return value. 


vO, v1, V2N -> VX, Vy, VZ : (1, 15, 0) 

SXy0, Sxy7, Sxy2 : (1, 15, O), (1, 15, 0) 
p : (0, 20, 12) 

flag : (0, 32, O) 


Return value 
1/4 of the screen coordinate Z component sz corresponding to v2. 


See also 
TransRotPers(), RotTransPers3(), TransRot_32() 
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TransRot_32 


Inversely perform rotation parallel move of RotTrans(). 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 3.2 12/14/98 

Syntax 

void TransRot( 

VECTOR *v0, Pointer to vector (input) 

VECTOR *v1, Pointer to vector (output) 

long *flag) Pointer to flag (output) 

Explanation 

After adding the 32 bit parallel move volume to vO, performs rotation with constant rotation matrix. 

VO -> VX, Vy, VZ : (1, 31, 0) 

v1 -> VX, W, VZ : (1, 31, 0) 

flag : (0, 32, 0) 

See also 


TransRotPers(), TransRotPerss(), RotTrans() 
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VectorNormal 
Normalize a vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 


Syntax 

void VectorNormal( 

VECTOR *vO, Pointer to vector (input) 

VECTOR *v7) Pointer to vector (output) 

Explanation 

Normalizes a vector vO and returns the result in v7. 

VO -> Vx, VY, VZ : (1, 31, 0) 

V1 -> VX, VY, VZ : (1, 19, 12) 

Warning: if (v0->vx)^2 + (v1->vx)^2 +(v2->vx)42) > Ox7FFFFFF, a processor exception will occur. 


Return value 
Sum of squared vO elements. 


See also 
VectorNormalS(), VectorNormalSS() 
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VectorNormalS 
Normalize a vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 3.0 12/14/98 


Syntax 

long VectorNormalS( 

VECTOR *vO, Pointer to vector (input) 
SVECTOR *v1) Pointer to vector (output) 
Explanation 

Normalizes a vector vO and returns the result in v7. 

VO -> VX, VY, VZ : (1, 31, 0) 
V1 -> VX, W, VZ : (1,3, 12) 
Warning: if (v0->vx)^2 + (v1->vx)^2 +(v2->vx)42) > Ox7FFFFFF, a processor exception will occur. 
Return value 

Sum of squared vO elements 


See also 
VectorNormal(), VectorNormalSS() 
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VectorNormalSS 
Normalize a vector. 


Library Header File Introduced Documentation Date 
libgte.lib liogte.h 2.X 12/14/98 

Syntax 

long VectorNormalSS( 

SVECTOR “vO, Pointer to vector (input) 

SVECTOR “v7) Pointer to vector (output) 

Explanation 

Normalizes a vector vO and returns the result in v7. 

VO -> Vx, VY, VZ : (1, 16, 0) 

V1 -> VX, W, VZ : (1,3, 12) 

Warning: if (v0->vx)^2 + (v1->vx)^2 +(v2->vx)42) > Ox7FFFFFF, a processor exception will occur. 

Return value 

Sum of squared vO elements 


See also 
VectorNormal(), VectorNormalS() 
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Structures 
GsBG 
BG (background surface) handler. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsBG { 
u_long attribute; Attribute 
short x, y; Top left point display position 
short w, h; BG display size 
short scrollx, scrolly; x and y scroll values 
u_char Fr, g, b; Display brightness is set in r, g, b. (Normal brightness is 128.) 
GsMAP *map; Pointer to map data 
short mx, my; Rotation and enlargement central point coordinates 
short scalex, scaley; Scale values in x and y directions 
long rotate; Rotation angle (4096 = 1 degree) 
} 
Explanation 


For attribute, see the description in GSSPRITE. 


A BG (background) is drawn as a large rectangle based on GsMAP data on a combination of small 
rectangles defined by GsCELL data. There is a GSBG for each BG. The BG may be manipulated via the 
GsBG structure. 


To register a GSBG object in the ordering table, use GsSortBg(). 

X, y specifies the screen display position. 

w, h specifies BG display size in pixels, and is not dependent on cell size or map size. 

If the display area is larger than the map, the content of the map is repeatedly displayed. (Tiling function) 
scrollx, scrolly specifies offset from the map display position in dots. 


r, g, b specifies brightness values for red, green, and blue. The range is O to 255. 128 is the brightness of 
the original pattern; 255 doubles the brightness. 





map specifies the starting address of map data with a pointer to GSMAP format map data. 


mx, my specify the center of rotation and scaling as relative coordinates. The top left point of the BG is the 
point of origin. For example, if rotation is around the center of the BG, specify w/2 and h/2. 





scalex, scaley specifies enlargement/reduction values in the x and y directions. These values are expressed 
in units of 4096, which stands for 1.0 (i.e. is the same size as 1.0). You can set these values up to 8 times 
the original size. 





rotate specifies a rotation angle around the z-axis (4096 = 1 degree). 


See also 
GslnitFixBg16(), GsSortBg(), GsSortFixBg16() 
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GsBOXF 
Rectangle handler. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GSBOXF { 
u_long attribute; Attribute (see GsLINE attributes) 
short x, y; Display position (top left point) 
u_short w, h; Size of rectangle (width, height) 
u_char r, g, b; Drawing color 
} 
Explanation 


GsBOXF is a structure used to draw a rectangle in a single color. To register GSBOXF in the ordering table, 
use GsSortBoxFill(). 


See also 
GsSortBoxFill() 
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GsCELL 
Cells constituting BG. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsCELL { 
u_short u Offset (X-direction) within the page 
u_short v; Offset (Y-direction) within the page 
u_short cba; CLUT ID 
u_short flag; An option at the time of drawing 
u_short tpage; Texture page number 
Explanation 


A rectangular array of GSCELL structures is used to describe individual cells that fit together to create a 
BG. Each individual GSCELL structure defines a rectangular portion of the overall BG. 


cba specifies the position within the frame buffer of a CLUT corresponding to the cell. Bits 0-5 are the X 
position of the CLUT divided by 16. Bits 6-15 are the Y position of the CLUT. 


toage is a page number that indicates the position of a Sprite pattern within a frame buffer. 








The u and v parameters specify the offset position for the sprite pattern within the texture page defined by 
tpage. 
flag specifies drawing options. Bit O is Vertical flip (O: no flip; 1: flip). Bit 1 is Horizontal flip (O: no flip; 1: flip). 
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GsCOORD2PARAM 
GsCOORDINATE2 parameter format. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.0 12/14/98 
Structure 
struct { 
VECTOR scale; Retains coordinate scaling information 
SVECTOR rotate; Retains coordinate rotation information 
VECTOR trans; Retains coordinate parallel shift information 
} GSCOORD2PARAM; 
Explanation 


This structure is used in order to retain information for GSCOORDINATE2 when TOD animation is used. 
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GsCOORDINATE2 
Matrix type coordinate system. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 9/1/99 
Structure 
struct GSCOORDINATE2 { 
u_long fig; Flag indicating whether coord was rewritten 
MATRIX coord; Matrix 
MATRIX workm; Result of multiplication from this coordinate system to the WORLD 
coordinate system 
GsCOORD2PARAM “param; Pointer for scale, rotation, and transfer parameters 
GsCOORDINATE2 “super; Pointer to superior coordinates 
GsCOORDINATE2 “sub; Not in current use 
} 
Explanation 


GsCOORDINATE2 has superior coordinates and is defined by the matrix type coord. 


workm retains the result of multiplication of matrices performed by GsGetLw() and GsGetLs() in each node 
of GSCOORDINATE2 using the WORLD coordinates. 


flg is referenced to omit calculations for a node for which calculations were already made, during GsGetLw() 
calculations. The external variable PSDCNT sets the flag and O clears it. If you change the contents of 
coord, you must clear this flag. If you neglect to clear it, GsGetLw() and GsGetLs() will fail to execute 
normally. 


param is used for setting coord values with layout tools. It may be freely used if TOD animation is not used. 


See also 
GsGetLs(), GsGetLw(), GsGetLws(), GsInitCoordinate2() 
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GsDOBJ2 
Three-dimensional object handler 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 
Structure 
struct GSDOBJ2 { 
u_long attribute; Object attribute (82-bit) 
GsCOORDINATE2 *coora2; Pointer to a local coordinate system 
u_long *tma; Pointer to model data 
u_long id; Reserved by the layout tool 
} 
Explanation 


Used to manipulate objects in a three-dimensional model. There is a GSDOBU2 for each object in a model. 


Use GsLinkObject4() to link a GSDOBJ2 to TMD-format model data. It sets tmd to the starting address of 
the TMD model object in memory. 


Use GsSortObject4() to register GSDOBU2 in the ordering table. 


coord? is a pointer to a GSCOORDINATE2 structure defining the object’s coordinate system. The location, 
inclination, and size of the object is defined in coord2->coord. 


attribute is a 32-bit value containing various display attributes: 
e Bits 0-2: material attenuation. (Note: currently not supported) 


Sets the relationship between the normal gradient and brightness attenuation for light source 
calculations. Values range from O (no attenuation) to 3 (steepest attenuation). This value affects an 
object's material quality: for example, a steep attenuation generally produces a metallic quality. Also 
note that the higher the value, the longer the processing time. 


Note: This parameter is invalid unless the lighting mode sets material attenuation on. 











e Bits 3-5: lighting mode 


Sets the light source calculation formula. Bit 5 is a switch to validate the default lighting mode set by 
GsSetLightMode(). The values of bits 3-4 can be: 


Table 9-1: Lighting modes 








Value Operation 

O Normal (fastest) mode. 

1 Fog only mode. Use GsSetFogParam() to 
set the fog parameter GSFOGPARAM. 

2 Material attenuation only mode. 

3 Applies both fog and material attenuation. 


Not currently supported. 





e Bit6: Light source calculation ON/OFF switch (1 = off) 


Improves processing speed by eliminatin light source calculation. A texture-mapped polygon is 
displayed in the original texture color; an unmapped polygon is displayed in the model data color. 


e Bit7: Near clipping 


If this bit is set, in cases where the polygon end point is very close to the viewpoint (distance between 
viewpoint and polygon < (distance between viewpoint and screen) /2), a polygon that has overflowed 
during perspective transformation will not be simply clipped, but can be forcibly displayed, even if its 
shape is distorted. 








Run-Time Library Reference 


Extended Graphics Library Structures 


e = Bit 8: Back clipping 


A polygon has a front and back determined by the order of its vertices. In the case of a convex object, 
it is not necessary to display the back face, so a back-facing polygon will be clipped. However, if this 
bit is set, a back-facing polygon can be displayed. 


The current version does not support back clipping. 








e Bits 9-11: Automatic division 


This operation subdivides an object’s component polygons at the time of execution. The number of 
divisions possible are: 2x2 (1), 4x4 (2), 8x8 (8), 16x16 (4), or 32x32 (5). 


You can use this operation to eliminate the problems accompanying a perspective transformation, 
such as texture distortion and Near clipping. You must take care that memory use and processing 
speed are not adversely impacted as the number of divisions increase. 

GsSortObject4() and GsSortObject5() are functions that create packets capable of automatic division. 
When using automatic division, you must pass the scratch pad address, used as a working argument, 
in the last argument of the packet creation function. 





e Bits 28-29: Semi-transparency rate (Note: currently not supported) 


Sets the pixel-blending formula when semi-transparency is set to ON in bit 30. 


Table 9-2: Semi-transparency Rate 








Value Background Primitive Processing 

O 0.5 0.5 Normal semi-transparency processing 
1 1.0 1.0 Pixel addition 

2 1.0 -1.0 50% addition 

3 1.0 0.25 Pixel subtraction 





e = Bit 30: Semi-transparency ON/OFF 


Used with the high (STP) bit of the texture color field (direct texture pattern or CLUT color field when 
indexed) to set semi-transparency. The semi-transparency and non-transparency of each pixel unit 
may be controlled using this STP bit. 


e Bit31: Display ON/OFF 


When the object is not displayed, speed is improved. 


See also 
GsLinkObject4(), GsSortObject4(),GsSortObject4J(), GsSetLightMode() 
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GsDOBJ3 
Three-dimensional object handler for use with PMD format. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 
Structure 
struct GSDOBJ3 { 
u_long attribute; Object attribute (32-bit) 
GsCOORDINATE2 *coord2; Pointer to a local coordinate system 
u_long “oma; Pointer to model data (PMD FORMAT) 
u_long “base; Pointer to object base address 
u_long “sv; Pointer to shared vertex base address 
u_long id; Reserved by the layout tool 
} 
Explanation 


There is a GSDOBUS for each object of a 3-dimensional model; GSDOBUS structures may be used to 
manipulate the 3-dimensional model. 


Use GsLinkObject3() to link GSDOBUJ3 to PMD file model data. 


You can use GSDOBJ3 to access PMD data linked by GsLinkObject3(). Use GsSortObject3() to register 
GsDOBUJS in the ordering table. 


coord? is a pointer to a coordinate system unique to an object. The location, inclination, and size of the 
object is reflected in a matrix set in the coordinate system to point to coord2. 


pmd retains the starting address of PMD model data stored in memory. pmd is calculated and set using 
GsLinkObject3(). 


attribute is 32-bit; various display attributes are set here. 


Only the attribute shown below is currently available. 





e Bits 0-30: Reserved, set to zero 
e = Bit 81: Display ON/OFF 


This turns display ON and OFF. 


id is not used unless the layout funtion is used. 


See also 
GsLinkObject3(), GsSortObject3() 
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GsDOBJ5 
Three-dimensional object handler for use with GsSortObject5(). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 
Structure 
struct GSDOBUJ5 { 
u_long attribute; Object attribute (32-bit) 
GsCOORDINATE2 *coord2; Pointer to local coordinate system 
u_long “tmd; Pointer to model data 
u_long “packet; Pointer to preset packet area 
u_long id; Reserved by the layout tool 
Explanation 


There is a GSDOBU5 for each object of a 3-dimensional model; GSDOBU5 structures may be used to 
manipulate the 3-dimensional model. 


Use GsLinkObject5() to link GSDOBJ5 to TMD file model data. 


You can use GSDOBU5 to access TMD data linked by GsLinkObject5(). Use GsSortObject5() to register 
GsDOBUJ5 in the ordering table. 


coord2 is a pointer to a coordinate system unique to an object. The location, inclination, and size of the 
object is reflected in a matrix set in the coordinate system to point to coord2. 


tmd retains the starting address of TMD model data stored in memory. tmd is calculated and set using 
GsLinkObject5(). 


packet retains the starting address of a preset packet copied into memory. A preset packet is copied by 
GsPresetObject(), and is set in a GSDOBJ5 packet. 


attribute is 32-bit; various display attributes are set here. An explanation of each bit follows. 











e Bits 0-2: Material attenuation (not currently supported) 


This sets the relationship between the normal gradient and brightness attenuation when light source 
calculation is performed. This takes a value of 0-3. With O there is no attenuation; the steepest 
attenuation is with 3. This parameter can be used to display an object's material quality. In general, 
making the attenuation steep produces a metallic quality. 


Note the following points: 


(a) If the material attenuation value is high, calculation takes longer and the processing requires a lot of 
resources. 


(b) This parameter is invalid In lighting mode unless material ON is set. 


e Bits 3-5: Lighting mode 








This sets the light source calculation formula. It takes a value of 0-3. The values are as listed below. 
e Bit 5, the highest ranking bit, is a switch to validate the lighting mode set by GsSetLightMode(). 


Table 9-3: Lighting Modes 








Value Operation 

0 Normal mode without fog or material attenuation. This is 
the fastest mode and calculation takes least time. 

1 Fog only mode. The fog parameter is GSFOGPARAM; 
set the parameter with GsSetFogParam(). 

2 Material attenuation only mode. The amount of 





attenuation is set by the material attenuation bit. Not 
currently supported. 
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Value Operation 
3 Applies both fog and material attenuation. Not currently 
supported. 





e Bit 6: Light source calculation ON/OFF switch 


This bit is used when light source calculation is not performed. When light source calculation is 
removed, a texture-mapped polygon is displayed in the original texture color. An unmapped polygon is 
displayed in the model data color. 


e Bits 7-30: Reserved, set to zero. 
e = Bits 31: Display ON/OFF 
This turns display ON and OFF. 
id is not used unless the layout functon is used. 





See also 
GsLinkObject5(), GsSortObject5(), GsSortObject5uU() 
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GsFOGPARAM 
Fog (depth cueing) information. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GSFOGPARAM { 
short dqa; Parameter for the degree of merging due to depth 
long dab; Parameter for the degree of merging due to depth. 
u_char rfc, gfc, bfc; Background colors 
} 
Explanation 


dqa and dqb are background color attenuation coefficients. They can be calculated using the following 
formulas: 


DQA = -df * 4096/64/h 
DQB = 1.25 * 4096 * 4096 


df is the distance where the attenuation coefficient is 1; that is, the distance from the viewpoint to where 
the background colors are completely blended. h indicates a projection, or a distance from the visual point 
to the screen. 





See also 
GsSetFogParam() 
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GsF_LIGHT 
Parallel light source. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsF_LIGHT { 
int vx, vy, vZ; Directional vectors for light source 
u_char Fr, g, b; Light source colors 
} 
Explanation 





Holds information about a parallel light source. Use GsSetFlatLight() to assign the values to one of three 
light sources.. 


The light source directional vectors are specified by vx, vy, vz. It is unnecessary for the programmer to 
perform normalization, because the system does it. A polygon whose normal vectors are opposite to these 
directional vectors is exposed to the strongest light. 





See also 
GsSetFlatLight() 
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GsGLINE 
Straight line handler with gradation. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.5 12/14/98 
Structure 
struct GsLINE { 
u_long attribute; Attribute (see GsLINE attributes) 
short xO, yO; Drawing start point position 
short x1, y1; Drawing end point position 
u_char r0, gO, bO; Drawing colors of start point 
u_char r1, g1, 67; Drawing colors of end point 
} 
Explanation 


GsGLINE is a structure used to draw straight lines with gradation. It is the same as GsLINE except that 
drawing colors for the starting point and end point may be specified separately. 


See also 
GsSortGLine() 
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GsIMAGE 
Information on image data composition. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsIMAGE { 
u_long pmode; Pixel mode. 
O: 4-bit CLUT 
1: 8-bit CLUT 


2: 16-bit DIRECT 
3: 24-bit DIRECT 
4: Coexistence of multiple modes 


short px, py; Pixel data storage location within the frame buffer 
u_short pw, ph; Pixel data width and height 
u_long “pixel; Pointer to pixel data 
short cx, cy; CLUT data storage location within the frame buffer 
u_short cw, ch; CLUT data width and height 
u_long *clut; Pointer to CLUT data 

} 

Explanation 


A structure in which TIM format data information is stored by GsGetTimInfo(). 


See also 
GsGetTiminfo() 
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GsLINE 
Straight line handler. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsLINE { 
u_long attribute; Attribute (see Explanation) 
short xO, yO; Drawing start point position 
short x7, y1; Drawing end point position 
u_char Fr, g, b; Drawing color 
} 
Explanation 


GsLINE is a structure for drawing straight lines. Use GsSortLine() to register a GsLINE in the ordering table. 
attribute is 32 bits, and sets various attributes for display: 


e Bits 0-27: Reserved, set to 0. 
e Bits 28-29: Semi-transparency rate 


If semi-transparency is turned on using bit 30, bits 28 and 29 are used to set the pixel blending method. 





6) 50% x Back + 50% x Line 

1 100% x Back + 100% x Line 
2 100% x Back + 50% x Line 
3 100% x Back - 100% x Line 


Bit 30: Semi-transparency ON/OFF: 1 = ON; 0 = OFF 
Bit 31: Display ON/OFF: 0 = displayed; 1 = not displayed 


See also 
GsSortLine() 
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GsMAP 
Map comprising BG. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsMAP { 
u_char cellw, cellh; Cell size (O is treated as 256.) 
u_short ncellw, ncellh; Size of BG (in cells) (Not displayed if w or h is 0.) 
GsCELL *base; Pointer to GSCELL structure array 
u_short “index; Pointer to cell information 
} 
Explanation 
GsMAP is map data used to compose BG from GsCELL. Map data are managed by cell index array 
information. 


cellw, cellh specify the size of one cell in pixels. Note that one BG is made up of cells of the same size. 





ncellw and ncellh set the size of the BG map in cells. 


base sets the starting address of the GsCELL array. 





index sets the starting address of the cell data table. Cell data is a list of index values whose size is 
equivalent to (ncellw*ncellh) for the array specified by base. If a cell value is OxFFFF it indicates a NULL 
(transparent) cell. 
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GsOBJTABLE2 
Object table information. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GSOBJTABLE2 { 
GsDOBU2 *top; Pointer to object array 
int nobj; Number of valid objects in array 
int maxobj; Size of object array 
Explanation 


When the three-dimensional animation function group is used, a three-dimensional object must be in the 
array in order to give effect to the object ID number specification. This array is called an object table. 
GsOBJTABLE2 contains information relating to the object table. 








top is a pointer to the GSDOBUJ2 array, within which the three-dimensional object managed by ID is 
created. The GSDOBU2 array must be allocated prior to object table initialization. 





maxobj is the size of array indicated by top; its value must be greater than the maximum value of the object 
handled. 


nobj is the number of valid objects within the array. 
GsOBJTABLE2 is initialized by GsInitObjTable2(). 
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GsOT 
Ordering table header. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GsOT { 
u_long /ength; Bit length of OT 
GsOT_TAG “org; Pointer to start address of GSOT_TAG table 
u_long offset; OT screen coordinate system Z-axis offset 
u_long point; OT screen coordinate system Z-axis typical value 
GsOT_TAG *tag; Pointer to current GSOT_TAG element 
} 
Explanation 





The GsOT structure describes the header of the ordering table format supported by libgs. This header has 
pointers to the actual ordering table array, specified by the org and tag members. These members are 
initialized using GsClearOT(). 





org always points to the start of the ordering table. tag points to the element within the ordering table at 
which drawing takes place. 


length sets the size of the ordering table, in values from 1-14. The actual ordering table size is 2**/ength (i.e. 
a value of 14 indicates an array of 16384 GsOT_TAG items, while a value of 8 indicates an array of 256 
GsOT_TAG items). 


length and org values should be set first. The other members are set by GsClearOt(). 





GsClearOt( initializes memory from org through to the size indicated by length. Note that memory will be 
destroyed if the size of the GSOT_TAG array pointed to by org is greater than that specified by length. 


point is used by GsSortOt( in the sorting of ordering tables. 
The ordering table Z-axis offset is set by offset. For example, if offset = 256, the start of the ordering table is 
Z = 256. (Not yet supported.) 


See also 
GsClearOt(), GsDrawOt(), GsSortOt(), GsCutOt(). 
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GsOT_TAG 
Ordering table unit. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Structure 


struct GSOT_TAG { 
unsigned p : 24; Pointer to next item in ordering table list 
u_char num : 8; Number of words in current GPU packet (i.e. primitive) 


} 
Explanation 


A libgs ordering table is a linked list of GSOT_TAG structures and various types of GPU primitive structures. 
The p field of a GSOT_TAG structure indicates the least significant 24-bits of a pointer to the next item in 
the list. A value of OxFFFFFF indicates the end of the list. 


The GsOT structure is used by libgs to manage an array of GSOT_TAG items. Allocate an array of 
GsOT_TAG structures after initializing your GSOT structure. 
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GsRVIEW2 
View handler (Reference type). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GSRVIEW2 { 
long vpx, vpy, vpz; Viewpoint coordinates 
long vrx, vry, VIZ; Reference point coordinates 
long rz; Viewpoint twist 
GsCOORDINATE2 *super; Pointer to the coordinate system that sets the viewpoint 
} 
Explanation 


GsRVIEW2 holds viewpoint information, and is set in libgs by GsSetRefView2(). vox, vpy, vpz are the 
viewpoint coordinates in the coordinate system displayed by super. 


vrx, vry, vrz are the reference point coordinates in the coordinate system displayed by super. 


When the z axis is a vector from the viewpoint to the reference point, rz specifies the screen inclination 
against the z axis in fixed decimal format, with 4096 equivalent to one degree. 


Viewpoint and reference point coordinate systems are set in super. As an example of using this function, an 
airplane cockpit view can be realized simply by setting super to the airplane coordinate system. 


See also 
GsSetRefView2(), GsSetRefView2L() 


Run-Time Library Reference 


Extended Graphics Library Structures 9-23 








GsSPRITE 
Sprite handler. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 
Structure 
struct GSSPRITE { 
u_long attribute; 82 bits (see Explanation) 
short x, y; Screen display position of the top left point 
u_short w, h; Width and height of Sprite in pixels (Not displayed if w or h is 0.) 
u_short tpage; Sprite pattern texture page number (0-31) 
u_char u, v; Sprite pattern offset within the page from top left point. Range is ((0, O) - 
(255, 255). 
short cx, cy; Starting position of CLUT in VRAM. (Valid for 4-bit/8-bit mode only) 
u_char Fr, g, b; Red, green, blue brightness values (0-255; original brightness is 128.) 
short mx, my; Rotation and enlargement central point coordinates 
short scalex, scaley; Scaling values in x and y directions (4096 = 1.0); can be up to 8 times 
original size 
long rotate; Sets rotation around the z-axis in fixed-decimal format (4096 = 1 degree) 
} 
Explanation 


A structure used to handle a Sprite. Makes it possible to manipulate each Sprite via its parameters. 
To register a GSSPRITE in the ordering table, use GsSortFlipSprite(), GsSortSprite(), or GsSortFastSprite(). 





mx, my specify the coordinates used as the center of rotation and scaling. For example, if rotation is 
desired around the center of the Sprite, specify w/2 and h/2 as mx and my. 


attribute is 32 bits, and sets various attributes for display. An explanation of each bit follows. 


e Bits 0-5: Reserved, set to zero. 
e Bit 6: Brightness adjustment ON/OFF switch 


This bit sets Sprite pattern pixel colors according to (r, g, b) values. If this bit is set to 1, brightness is 
not adjusted, and (r, g, 6) values are ignored. 


e Bits 7-21: Reserved, set to zero. 

e Bits 22-23: Vertical flipping, horizontal flipping 
O = not flipped; 1 = flipped 

e Bits 24-25: Color mode 


A Sprite pattern has 4-bit mode and 8-bit mode, both of which use the color table, and 15-bit mode, 
which directly displays colors. These bits are used to select any of these modes. 


O = 4-bit CLUT; 1 = 8-bit CLUT; 2 = 15-bit direct. 
e Bit 26: Reserved, set to zero. 
e = Bit 27: Rotation enlargement/reduction function 


This bit turns on or off the Sprite enlargement function (O = on, 1 = off). If rotation or enlargement of the 
Sprite is not needed, this bit should be set to OFF for high speed processing. 


GsSortFastSprite() and GsSortFlipSprite() ignore this bit and always set the enlargement function to off. 
e Bits 28-29: Semi-transparency rate 


When semi-transparency is set to ON with bit 30, the semi-transparency rate sets the pixel-blending 
formula: 
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Table 9-4: Semi-transparency Rate 





(0 


Normal semi-transparency processing 


50% x Back + 50% x Sprite 





Pixel addition 


100% x Back + 100% x Sprite 





50% addition 


100% x Back + 50% x Sprite 





1 
2 
3 








Pixel subtraction 





100% x Back - 100% x Sprite 





e = Bit 80: Semi-transparency ON/OFF (1 = on, O = off) 
This bit must be used with the uppermost bit (STP bit) of the texture color field (texture pattern when 
direct and CLUT color field when indexed) to set semi-transparency,. Also, the semi-transparency and 
non-transparency of each pixel unit may be controlled using this STP bit. 


e = Bit 31: Display ON/OFF (O = displayed, 1 = not displayed) 





This turns display ON and OFF. 


SPRT primitives are used when neither rotation, enlargement, nor reduction are performed by 
GsSortSprite(. Consequently, it is necessary to keep track of whether the uv, wh of a texture is odd or 


even. 


GsSortFlipSprite() uses POLY_FT4 unconditionally. 








With GsSortSprite(, w, h are set to 1 less than the desired dimensions, to handle the lower-right texture 
page problem. Consequently, the texture is displayed slightly enlarged. (When programming, the lower- 
right line can be included, since reduction takes place within the function.) 





Since GsSortFlipSprite() displays POLY_FT4 at the original scale, the rendering rules dictate that the lower 
right corner cannot be used. When flipping, to ensure proper display, the lower left line should not be used 


either. 


See also 


GsSortFlipSprite(), GsSortSprite(), GsSortFastSprite() 
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GsVIEW2 


View handler (matrix type). 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Structure 


struct GsVIEW2 { 
MATRIX view; Matrix used to change from superior coordinates to viewpoint 
coordinates 
GsCOORDINATE “super; Pointer to the coordinate system that sets viewpoint 


Explanation 


Sets the viewpoint coordinate system, and specifies the matrix used by view to change from superior 
coordinates to viewpoint coordinates. 


The function that sets GsVIEW2 is GsSetView2\(). 


See also 
GsSetView2() 
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TMD_STRUCT 
TMD data object header. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long *vertop; VERTEX start address 
u_long vern; VERTEX coefficient 
u_long *nortop; NORMAL start address 
u_long norn; NORMAL coefficient 
u_long “primtop; PRIMITIVE start address 
u_long primn; PRIMITIVE coefficient 
u_long scale; Scaling factor 


} TMD_STRUCT; 


Explanation 


A structure in the OBJ TABLE section within the TMD data. It contains information regarding the pointer 
which displays where each object is stored. 
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_GsFCALL 

The function table for GsSortObject4J() and GsSortObject5uJ\(). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Structure 


struct _GsFCALL { 
PACKET *(*/3/21/3))0, *“(nf3[2))0,*9S[2I[8) 0,*Cngs[2)0; 
PACKET *(*t/3/2/[3))0, *(*ntf3/2))0), *(tg3[2][3) 0, *Cntg3[2))0; 
PACKET *(*/4/21/3))0,*“(nf4[2))0,"*(94[2I[S)0,*C"ng4[e2)0; 
PACKET *(*tf4/2/[3))0, *(*ntf4[2))0), “(tg 4/(2][8) 0, *Cntg4[2))0; 
PACKET *(*/39/3))0), *(‘93g/8))0; 

i PACKET *(*/49/3))) “C9491390; 


Members 
Each member is a pointer to a low-level function. 


13, g3, tf8, tg3, f4, 94, tf4, tg4 Pointer to polygon types 

First matrix: Division/no division 
GsDivMODE_DIV/GsDivMode_NDIV 

Second matrix: Light source calculation mode 


GsLMODE_NORMAL/GsLMODE_FOG/ 
GsLMODE_LOFF 
nf3, ng3, ntt3, ntg3, nf4, ng4, ntf4, ntg4 Pointer to polygon types 


First matrix: Division/no division 
GsDivMODE_DIV/GsDivMode_NDIV 

13g, 939, f4g, 94g Gradation polygon type 

First array: Light source calculation mode 


GsLMODE_NORMAL/GsLMODE_FOG/ 
GsLMODE_LOFF 


Explanation 


GsSortObject4() and GsSortObject5() dispatch attributes, pre-set data, etc. and call low-level functions. 
There are 64 low-level functions, and a single application is unlikely to use all of them. 





With GsSortObject4J() and GsSortObject5J(), you don't need to link with unnecessary low-level functions, 
thereby making the code more compact. These functions are compatible with GsSortObject4() and 
GsSortObject5(), which organize low-level functions as tables. 


_GsFCALL is the structure in which the function table is defined. The function table is organized according 
to polygon type, whether or not division is performed, and light-source calculation mode. 


The relevant functions are linked by entering the pointers of the appropriate low-level functions in each of 
the elements. It is possible to avoid linking by not including the pointers and not making extern 
declarations. However, if a function that does not have a pointer is called, a BUS ERROR is generated. 





The example below shows the use of GsSortObject5() with appropriate functions in all the elements. In this 
example, GsSortObject5J() functions the same as GsSortObject5(). This example is included in comments 
in the file libgs.h. 


/* extern and fook only using functions */ 
extern _GsFCALL GsFCALL5; /* GsSortObject5J Func Table */ 
jt_init () /* Gs SortObject5J Fook Func */ 
{ 
PACKET *GsPrstF3NL(),*GsPrstF3LFG(),*GsPrstF3L(),*GSPrstNF3(); 
PACKET *GSTMDdivF3NL(),*GSTMDdivF3LFG(),*GSTMDdivF3L(),*GsSTMDdivNF3(); 
PACKET *GsPrstG3NL(),*GsPrstG3LFG(),*GsPrstG3L(),*GsPrstNG3 (); 
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PACKET *GsTMDdivG3NL(),*GSTMDdivG3LFG(),*GSTMDdivG3L(),*GsSTMDdivNG3 () ; 
PACKET *GsPrstTF3NL(),*GsPrstTF3LFG(),*GsPrstTF3L(),*GsPrstTNF3 (); 
PACKE *Gs DdivTF3NL(),*GSTMDdivTF3LFG(),*GSTMDdivTF3L(),*GSTMDdivINF3 () ; 
PACKET *GsPrstTG3NL(),*GsPrstTG3LFG(),*GsPrstTG3L(),*GsPrstTING3 (); 
PACKET *GsTMDdivTG3NL (),*GSTMDdivTG3LFG(),*GsTMDdivTG3L(),*GSTMDdivING3 (); 
PACKET *GsPrstF4NL(),*GsPrstF4LFG(),*GsPrstF4L(),*GSPrstNF4 (); 
PACKET *GsSTMDdivF4NL(),*GSTMDdivF4LFG(),*GSTMDdivF4L(),*GSTMDdivNF4 (); 
PACKET *GsPrstG4NL(),*GsPrstG4LFG(),*GsPrstG4L(),*GsPrstNG4 (); 
PACKET *GsTMDdivG4NL(),*GsSTMDdivG4LFG(),*GsSTMDdivG4L() , *GSTMDdivNG4 () ; 
PACKET *GsPrstTF4NL(),*GsPrstTF4LFG(),*GsPrstTF4L(),*GsPrstTNF4 (); 
PACKET *GsTMDdivTF4NL(),*GSTMDdivTF4LFG(),*GSTMDdivTF4L (),*GsSTMDdivINF4 (); 
PACKET *GsPrstTG4NL(),*GsPrstTG4LFG(),*GsPrstTG4L(),*GsPrstTING4 (); 
PACKET *GsSTMDdivTG4NL (),*GSTMDdivTIG4LFG(),*GsTMDdivTG4L(),*GSTMDdivTNG4 () ; 
PACKET *GsPrstF3GNL(),*GsPrstF3GLFG(),*GsPrstF3GL(); 
PACKET *GsPrstG3GNL(),*GsPrstG3GLFG(),*GsPrstG3GL(); 
/* flat triangle */ 
GsFCALL5.£3[GsDivMODE_NDIV] [GSLMODE_NORMAL] = GsPrstF3L; 
GsFCALL5.£3[GsDivMODE_NDIV] [GSLMODE_FOG] = GsPrstF3LFG; 
GsFCALL5.£3[GsDivMODE_NDIV] [GSLMODE_LOFF] = GsPrstF3NL; 
GsFCALL5.£3[GsDivMODE_DIV] [GSLMODE_NORMAL] = GsTMDdivF3L; 
GsFCALL5. £3 [GsDivMODE_DIV] [GSLMODE_FOG] = GsTMDdivF3LFG; 
GsFCALL5. £3 [GsDivMODE_DIV] [GSLMODE_LOFF] = GsTMDdivF3NL; 
GsFCALL5.nf3[GsDivMODE_NDIV] = GsPrstNF3; 
GsFCALL5.nf3[GsDivMODE_DIV = GsTMDdivNF3; 
/* gour triangle */ 
GsFCALL5.g3[GsDivMODE_NDIV] [GSLMODE_NORMAL] = GsPrstG3L; 
GsFCALL5.g3[GsDivMODE_NDIV] [GsLMODE_FOG] = GsPrstG3LFG; 
GsFCALL5.g3[GsDivMODE_NDIV] [GSLMODE_LOFF] = GsPrstG3NL; 
GsFCALL5.g3[GsDivMODE_DIV] [GSLMODE_NORMAL] = GsTMDdivG3L; 
GsFCALL5.g3[GsDivMODE_DIV] [GsLMODE_FOG] = GSTMDdivG3LFG; 
GsFCALL5.g3[GsDivMODE_DIV] [GSLMODE_LOFF] = GsTMDdivG3NL; 
GsFCALL5.ng3 [GsDivMODE_NDIV = GsPrstNG3; 
GsFCALL5.ng3 [GsDivMODE_DIV = GsSTMDdivNG3; 
/* texture flat triangle */ 
GsFCALL5.t£3[GsDivMODE_NDIV] [GsLMODE_NORMAL] = GsPrstTIF3L; 
GsFCALL5.tf£3[GsDivMODE_NDIV] [GSLMODE_FOG] = GsPrstTF3LFG; 
GsFCALL5.t£3[GsDivMODE_NDIV] [GsLMODE_LOFF] = GsPrstTF3NL; 
GsFCALL5.tf£3[GsDivMODE_DIV] [GsLMODE_NORMAL] = GsTMDdivTF3L; 
GsFCALL5.tf£3[GsDivMODE_DIV] [GsSLMODE_FOG] = GsTMDdivTF3LFG; 
GsFCALL5.tf£3[GsDivMODE_DIV] [GSLMODE_LOFF] = GsTMDdivTF3NL; 
GsFCALL5.ntf£3[GsDivMODE_NDIV] = GsPrstTNF3; 
GsFCALL5.ntf£3[GsDivMODE_DIV = GSTMDdivTNF3; 
/* texture gour triangle */ 
GsFCALL5.tg3 [GsDivMODE_NDIV] [GSLMODE_NORMAL] = GsPrstTG3L; 
GsFCALL5.tg3 [GsDivMODE_NDIV] [GSLMODE_FOG] = GsPrstTG3LFG; 
GsFCALL5.tg3 [GsDivMODE_NDIV] [GSLMODE_LOFF] = GsPrstTG3NL; 
GsFCALL5.tg3 [GsDivMODE_DIV] [GSLMODE_NORMAL] = GsTMDdivTG3L; 
GsFCALL5.tg3 [GsDivMODE_DIV] [GSLMODE_FOG] = GsTMDdivTG3LFG; 
GsFCALL5.tg3 [GsDivMODE_DIV] [GSLMODE_LOFF'] = GsTMDdivTG3NL; 
GsFCALL5.ntg3[GsDivMODE_NDIV] = GsPrstTING3; 
GsFCALL5.ntg3[GsDivMODE_DIV = GsTMDdivTING3; 
/* flat quad */ 
GsFCALL5.£4[GsDivMODE_NDIV] [GSLMODE_NORMAL] = GsPrstF4L; 
GsFCALL5.£4[GsDivMODE_NDIV] [GSLMODE_FOG] = GsPrstF4LFG; 
GsFCALL5.£4[GsDivMODE_NDIV] [GSLMODE_LOFF] = GsPrstF4NL; 
GsFCALL5.£4[GsDivMODE_DIV] [GSLMODE_NORMAL] = GsTMDdivF4L; 
GsFCALL5. £4 [GsDivMODE_DIV] [GSLMODE_FOG] = GsTMDdivF4LFG; 
GsFCALL5. £4 [GsDivMODE_DIV] [GSLMODE_LOFF] = GsTMDdivF4NL; 
GsFCALL5.nf4[GsDivMODE_NDIV] = GsPrstNF4; 
GsFCALL5.nf4[GsDivMODE_DIV = GsTMDdivNF4; 























/* gour quad */ 
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GsFCALL5.g4[GSDivMODE_NDIV] [GSLMODE_NORMAL] 
GsFCALL5.g4[GSDivMODE_NDIV] [GSLMODE_FOG] 
GsFCALL5 .g4[GsDivMODE_NDIV] [GSLMODE_LOFF] 
GsFCALL5.g4[GsDivMODE_DIV] [GSLMODE_NORMAL] 
GsFCALL5 .g4 [GSDivMODE_DIV] [GSLMODE_FOG] 
GsFCALL5 .g4[GsDivMODE_DIV] [GSLMODE_LOFF] 
GsFCALL5.ng4[GsDivMODE_NDIV 
GsFCALL5.ng4[GsDivMODE_DIV 

/* texture flat quad */ 
GsFCALL5.tf£4[GsDivMODE_NDIV] [GSLMODE_NORMAL] 
GsFCALL5.t£4[GsDivMODE_NDIV] [GSLMODE_FOG] 
GsFCALL5.tf£4[GsDivMODE_NDIV] [GsLMODE_LOFF] 
GsFCALL5.t£4[GsDivMODE_DIV] [GsLMODE_NORMAL] 
GsFCALL5.t£4[GsDivMODE_DIV] [GSLMODE_FOG] 
GsFCALL5.t£4[GsDivMODE_DIV] [GSLMODE_LOFF] 
GsFCALL5 .nt£4[GsDivMODE_NDIV] 
GsFCALL5.ntf4[GsDivMODE_DIV 

/* texture gour quad */ 

GsFCALL5.tg4 [GsSDivMODE_NDIV] [GSLMODE_NORMAL] 
GsFCALL5.tg4[GsDivMODE_NDIV] [GsLMODE_FOG] 
GsFCALL5 .tg4[GsDivMODE_NDIV] [GSLMODE_LOFF] 
GsFCALL5.tg4[GSDivMODE_DIV] [GSLMODE_NORMAL] 
GsFCALL5.tg4[GsDivMODE_DIV] [GSLMODE_FOG] 
GSFCALL5 .tg4[GsDivMODE_DIV] [GSLMODE_LOFF] 
GsFCALL5 .ntg4 [GsDivMODE_NDIV] 
GsFCALL5.ntg4[GsDivMODE_DIV 

/* gradation triangle */ 
GsFCALL5.f£3g[GsLMODE_NORMAL 
GsFCALL5.f3g[GsLMODE_FOG] 
GsFCALL5.f3g[GSLMODE_LOFF ] 
GsFCALL5.g3g[GsLMODE_NORMAL 
GsFCALL5.g3g[GsLMODE_FOG] 
GsFCALL5.g3g[GsLMODE_LOFF ] 


























GsSortObject4J(), GsSortObject5J(). 
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L; 








PrstG3G 


tG3GLFG; 








L; 


Run-Time Library Reference 


9-29 


9-30 Extended Graphics Library Structures 


_GsPOSITION 


Two-dimensional offset. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.0 12/14/98 


Structure 
struct _GsPOSITION { 
short offx; Rendering offset (x direction) 
short offy; Rendering offset (y direction) 
} 
Explanation 
Two-dimensional rendering offset. 
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Functions 
dmyGsPrst... 
Jump Table dummy function group (PMD) 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 
Syntax 


PACKET *dmyGsPrst... (void) 


Explanation 


When this function is called for the first time, the jump table entry name is printed to standard output. It is 
used as a low-level dummy function and is used when distinguishing which entry is being called. 


For debugging use. 


Return value 
Pointer to the packet. 
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dmyGsTMD... 

Jump Table dummy function group (TMD). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Syntax 


PACKET *dmyGsTMD... (void) 


Explanation 


When this function is called for the first time, the jump table entry name is printed in standard output. It is 
used as a low-level function dummy and is utilized when distinguishing which entry is being called. 


For debugging use. 


Return value 
Pointer to the packet. 
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GsA4div... 

Low-level functions for GsSortObject4uJ() (performs automatic division). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.1 12/14/98 

Syntax 

PACKET *GsA4div...( 

TMD_P_... *op, Pointer to starting address of TMD data primitives 

VERT *vp, Pointer to starting address of TMD data vertices TMD 

VERT “np, Pointer to starting address of TMD data normals 

PACKET “ok, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 

u_long “scratch) Pointer to starting address of unused scratch pad 


PACKET *GsA4divN...( 


TMD_P_... *op, Pointer to starting address of TMD data primitives 
VERT “vo, Pointer to starting address of TMD data vertices TMD 
PACKET “pk, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 

u_long “scratch) Pointer to starting address of unused scratch pad 
Explanation 


Performs active automatic division based on Z-values, polygon size, etc. 


To use these functions, they must be registered in GSFCALL4 as low-order functions, and the number of 
divisions must be specified in the attributes of GSDOBUJ4. 








Because each of these functions uses a relatively large amount of code, it would be more efficient to use 
only the code needed for the polygon types used. 





Parameters for division include Z-values, polygon size, and GTE calculation overflow flags. These are set 
using the GsSetAzwh (az, aw, ah) macro. 


The active division algorithm is as follows: 


1. Do not divide polygons that are further away than az and that do not cause overflow in GTE 
calculations. 

2. lf cases other than 1, perform divisions (go to step 3). 

3. If polygon size does not exceed aw, ah, and there is no overflow in GTE calculations, then halt division 
there. 


Otherwise, reduce by 1/2 in the x and y directions, and divide into four sections. Call step 3 recursively. If 
the maximum value for divisions (the number of divisions in attribute) is reached, then halt division. 





For function types which do not operate on normals within the data (e.g. GSA4divN...), light source 
calculations are not performed so fewer parameters are passed compared to those function types which 
operate on normals (e.g. GsA4div...), 





Low-level functions in libgs that support automatic division are shown below. 


Table 9-5: GsA4div...() [have normals] 








Low-level function First arg (op) tyoe Description 

name 

GsA4divF3L TMD_P_F3 Flat triangle (light source calculation) 
GsA4divF3LFG TMD_P_F3 Flat triangle (light source calculation +FOG) 
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Low-level function First arg (op) tyoe Description 
name 
GsA4divF3NL TMD_P_F3 Flat triangle 
GsA4divF4L TMD_P_F4 Flat quadrilateral (light source calculation) 
GsA4divF4LFG TMD_P_F4 Flat quadrilateral (light source calculation 
+FOG) 
GsA4divF4NL TMD_P_F4 Flag quadrilateral 
GsA4divG3L TMD_P_G3 Gouraud triangle (light source calculation) 
GsA4divG3LFG TMD_P_G3 Gouraud triangle (light source calculation 
+FOG) 
GsA4divG3NL TMD_P_G3 Gouraud triangle 
GsA4divG4L TMD_P_G4 Gouraud quadrilateral (light source 
calculation) 
GsA4divG4LFG TMD_P_G4 Gouraud quadrilateral (light source 
calculation +FOG) 
GsA4divG4NL TMD_P_G4 Gouraud quadrilateral 
GsA4divTF3L TMD_P_TF3 Textured flat triangle 
(light source calculation) 
GsA4divTF3LFG TMD_P_TF83 Textured flat triangle 
(light source calculation +FOG) 
GsA4divTF3NL TMD_P_TF3 Textured flat triangle 
GsA4divTF4L TMD_P_TF4 Textured flat quadrilateral 
(light source calculation) 
GsA4divTF4LFG TMD_P_TF4 Flat quadrilateral 
(light source calculation +FOG) 
GsA4divTF4NL TMD_P_TF4 Textured flat quadrilateral 
GsA4divTF4LM TMD_P_TF4 Textured flat quadrilateral 
(light source calculation +mip-map) 
GsA4divTF4LFGM TMD_P_TF4 Textured flat quadrilateral 
(light source calculation +FOG+mip-map) 
GsA4divTF4NLM TMD_P_TF4 Textured flat quadrilateral 
(mip-map) 
GsA4divTG3L TMD_P_TG3 Textured Gouraud triangle 
(light source calculation) 
GsA4divTG3LFG TMD_P_TG3 Textured Gouraud triangle 
(light source calculation +FOG) 
GsA4divTG3NL TMD_P_TG3 Textured Gouraud triangle 
GsA4divTG4L TMD_P_TG4 Textured Gouraud quadrilateral 
(light source calculation) 
GsA4divTG4LFG TMD_P_TG4 Textured Gouraud quadrilateral 
(light source calculation +FOG) 
GsA4divTG4NL TMD_P_TG4 Textured Gouraud quadrilateral 
GsA4divTG4LM TMD_P_TG4 Textured Gouraud quadrilateral 
(light source calculation +mip-map) 
GsA4divTG4LFGM TMD_P_TG4 Textured Gouraud quadrilateral 
(light source calculation+-FOG+mip-map) 
GsA4divTG4NLM TMD_P_TG4 Textured Gouraud quadrilateral 
(mip-map) 
Table 9-6: GsA4divN...() [no normals] 
Low-level function First arg (op) Description 
name type 
GsA4divNF3 TMD_P_NF3 Flat triangle 
GsA4divNF4 TMD_P_NF4 Flat quadrilateral 
GsA4divNG3 TMD_P_NG3 Gouraud triangle 
GsA4divNG4 TMD_P_NG4 Gouraud quadrilateral 
GsA4divTNF3 TMD_P_TNF3 Textured flat triangle 
GsA4divTNF4 TMD_P_TNF4 Textured flat quadrilateral 
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Low-level function First arg (op) Description 

name type 

GsA4divTNF4M TMD_P_TNF4 Textured flat quadrilateral 
(mip-map) 

GsA4divTNG3 TMD_P_TNG3 Textured Gouraud triangle 

GsA4divING4 TMD_P_TNG4 Textured Gouraud quadrilateral 

GsA4divTING4M TMD_P_TNG4 Textured Gouraud quadrilateral 


(mip-map) 





GsTMDadiv functions must be registered in GSFCALL4 when using the conventional fixed division method. 


Return value 


Starting address of unused packet area. 


See also 


GsTMDaiv...(, GsSetAzwh(), GsSortObject4J(). 
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GsClearOt 

Initialize a libgs ordering table structure. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsClearOt( 

u_short offset, Ordering table offset value 

u_short point, Ordering table average Z value 

GsOT “*otp) Pointer to ordering table 

Explanation 


Initializes the libgs-style ordering table specified by the oto parameter. The length field of the GSOT 
structure must be properly set before this function is called. offset specifies the Z-depth value used for the 
start of the ordering table. point represents the average Z-depth of the entire ordering table and is used to 
determine depth priority when linking multiple ordering tables together. 











See also 
GsDrawOt(), GsCutOt(), GsSortOt() 
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GsClearVcount 

Clear vertical retrace counter. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Syntax 


void GsClearVcount(void) 


Explanation 
Clears the vertical retrace counter. 


See also 
GsGetVcount(), GslInitVcount() 
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GsCutOt 


OT separation. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

GsOT *GsCutOt( 

GsOT “*ot_src, Pointer to old OT 
GsOT *ot_dest) Pointer to new OT 


Explanation 


Moves the drawing commands registered in the ot_src ordering table to the ot_dest ordering table. The 
length and tag fields of ot_src are reset to zero. The tag field of ot_dest is updated to point at the drawing 
command which was at the start of ot_src. Afterwards, ot_dest can be used to access the ordering table. 





Return value 
ot_dest starting address. 


See also 
GsClearOt(), GsDrawOt(), GsSortOt() 
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GsDefDispBuff 


Define double buffers. 





Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

void GsDefDispBuff ( 

u_short x0, u_short y0, Buffer O origin point coordinates (top left point) 
u_short x7, u_short y7) Buffer 1 origin point coordinates (top left point) 


Explanation 
Defines the display areas used for double-buffering. 
XO and yO specify the frame buffer coordinates for buffer #0. x7 and y1 specify the frame buffer coordinates 


for buffer #0. Normally, buffer #0 is located at (0,0) and buffer #1 is located at (0, yres), where yres is the 
vertical resolution specified using GsInitGraph(). 


If xO, yO and x1, y1 are specified as the same coordinates, the double buffers are released. However, 
double-buffer swapping of even-numbered and odd-numbered fields is performed automatically when xO, 
yO and x1, y1 are specified as the same coordinates in interlace mode. 





GsSwapDispBuffer() is used to swap double buffers. The double buffer is implemented by the GPU or GTE 
offset. Set the libgpu or libgte offset with GslnitGraph(). When using the libgpu offset, coordinate values 
based on the coordinate system using the upper left point in the double buffer as the origin are created in 
the packet (add the offset at the time of drawing, not at the time of packet preparation). 











See also 
GslnitGraph(), GsDefDispBuff2(), GsSwapDispBuffer(), GsGetActiveBuffer() 
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GsDefDispBuff2 


Define double buffers. 





Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 

void GsDefDispBuff2( 

u_short x0, u_short yO, Buffer O origin point coordinates (top left point) 
u_short x7, u_short y7) Buffer 1 origin point coordinates (top left point) 


Explanation 


Defines the double buffer. Differs from GsDefDispBufff) only in the modification of internal variables. These 
modifications are not updated in libgpu and libgte until GsSwapDispBuff() is called; for immediate update, 
call GsDefDispBuff() instead. 





Settings can be changed in the middle of the program without affecting the screen. 





See also 
GsDefDispBuff), GsSwapDispBuffer(), GsGetActiveBuffer() 
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GsDrawOt 

Process GPU commands registered to OT. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsDrawOt( 

GsOT “ot) Pointer to OT 

Explanation 


Starts execution of commands registered in OT, specified by ot. Because processing is performed in the 
background, GsDrawOt() returns immediately. 


See also 
GsClearOt(), GsCutOt(), GsSortOt(), GsDrawOtlO 
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GsDrawOtlO 

Process GPU commands (I/O version) allocated to OT. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.5 12/14/98 

Syntax 

void GsDrawOtlO( 

GsOT “ot) Pointer to OT 

Explanation 


Starts the execution of commands registered in OT, indicated by ot. Unlike GsDrawOt(), the processing is 
performed in the foreground; thus this function does not return until drawing is completed. 


Mainly used for debugging. 


See also 
GsDrawOt() 
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GsGetActiveBuffer 

Get a buffer number during drawing. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


int GsGetActiveBuffer(voic) 
Explanation 
Gets a double buffer index. Index values are either O or 1. 


By entering indexes in the external variables, PSDBASEX[] and PSDBASEY]], it is possible to determine the 
two-dimensional address of the double buffer origin point (top left coordinates) in the frame buffer. 











Return value 
Index of a double buffer (O for buffer O, and 1 for buffer 1) 


See also 
GsDefDispBuff), GsSwapDispBuffer() 
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GsGetLs 


Calculate a local screen matrix. 


Library Header File Introduced Documentation Date 
libgs. lib libgs.h 2.x 9/1/99 


Syntax 

void GsGetLs( 

GsCOORDINATE2 *coord, Pointer to local coordinates 
MATRIX *m) Pointer to matrix 


Explanation 


Calculates a local screen perspective transformation matrix from the GSCOORDINATE2 structure pointed 
to by the coord argument and stores the result in the MATRIX structure pointed to by the m argument. 


For high speed operation, the function retains the result of calculation at each node of the hierarchical 
coordinate system. When the next GsGetLs() function is called, calculation up to the node to which no 
changes have been made is omitted. This is controlled by a GSCOORDINATE2 member flag (libgs replaces 
the external variable PSDCNT in flags already calculated by GSCOORDINATE2). 


If the contents of a superior node are changed, the effect on a subordinate node is handled by libgs, so it is 
not necessary to clear the flags of all subordinate nodes of the changed superior node. 











See also 
GsGetLw(), GsGetLws() 
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GsGetLw 


Calculate a local world matrix. 


Library Header File Introduced Documentation Date 
libgs. lib libgs.h 2.x 9/1/99 


Syntax 
void GsGetLw( 


GsCOORDINATE2 *coord, Pointer to local coordinate system 
MATRIX *m) Pointer to matrix 


Explanation 


Calculates a local world perspective transformation matrix from the GSCOORDINATE2 structure pointed to 
by the coord argument and stores the result in the MATRIX structure pointed to by the m argument. 


For high speed operation, the function retains the result of calculation at each node of the hierarchical 
coordinate system. When the next GsGetLw() function is called, calculation up to the node to which no 
changes have been made is omitted. This is controlled by a GSCOORDINATE2 member flag (libgs replaces 
the external variable PSDCNT in flags already calculated by GSCOORDINATE2). 


If the contents of a superior node are changed, the effect on a subordinate node is handled by libgs, so it is 
not necessary to clear the flags of all subordinate nodes of the changed superior node. 











See also 
GsGetLs(), GsGetLws() 
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GsGetLws 

Calculate local world and local screen matrices. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsGetLws( 

GsCOORDINATE2 *coord2, Pointer to local coordinates 

MATRIX *w, Pointer to matrix that stores the local world coordinates 

MATRIX “/s) Pointer to matrix that stores the local screen coordinates 

Explanation 


GsGetLws() calculates local world and local screen coordinates. It is faster than calling GsGetLw() followed 
by calling GsGetLs(). When you use GsSetLightMatrix(), you pass it the Iw matrix. 


See also 
GsGetLw(), GsGetLs(), GsSetLightMatrix() 


Run-Time Library Reference 


Extended Graphics Library Functions 9-47 


GsGetTimIinfo 
Find TIM format header. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 


void GsGetTimInfo( 
u_long *tim, Pointer to TIM data 
GsIMAGE *im) Pointer to an image Structure 


Explanation 


Fills in the GSIMAGE structure pointed to by the im parameter with the appropriate information obtained 
from the TIM data located at the address specified by the tim parameter. 
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GsGetVcount 

Get the value of the vertical retrace counter. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


long GsGetVcount(voic) 


Explanation 
Gets the value of the vertical retrace counter. 





Return value 
Value of the vertical retrace counter. 





See also 
GsClearVcount(), GsInitVcount() 
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GsGetWorkBase 

Get address for storing current drawing commands. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.x 12/14/98 

Syntax 


PACKET *GsGetWorkBase(voic) 


Explanation 
Allocates and returns a pointer to a buffer used for generating a drawing primitive GPU packet. 


Return value 
Address to prepare the next drawing primitive packet. 
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GslInit3D 

Initialize the graphics system. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsInit3D(voiac) 


Explanation 


Initializes the libgs three-dimensional graphics system. It must be called before using other 3D functions 
such as GsSetRefView2(), GsInitCoordinate2(), and GsSortObject3\(). It does the following: 


e Brings the screen point of origin to the center of the screen. 
e Sets the light source to the LIGHT_NORMAL default. 
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GslInitCoordinate2 

Initialize a local coordinate system 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsInitCoordinate2( 

GsCOORDINATE2 “super, Pointer to a superior coordinate system 
GsCOORDINATE2 *base) Pointer to a coordinate system (to be initialized) 
Explanation 


Initializes the coordinate system base. base->coord is set to an identity matrix (GSIDMATRIX). super->sub 
is set to base. 
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GsInitFixBg16, GsInitFixBg32 


Initialize BG work area (high-speed) 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsInitFixBg1 6( 

GsBG *bg, Pointer to GSBG 

u_long *work) Pointer to work area (primitive area) 


void GslInitFixBg32( 


GsBG “bg, Pointer to GSBG 
u_long *work) Pointer to work area (primitive area) 
Explanation 


These functions initialize the work area used by the functions GsSortFixBg16() and GsSortFixBg32(), 
respectively. The size of the array differs with the screen mode as follows: 


size (in long units)=(((ScreenW/CellW+1) x (ScreenH/CellH+1+1) x 6+4) x 2+2) 
ScreenH: screen height in pixels (240/480) 

ScreenW: screen width in pixels (256/3820/384/51 2/640) 

CellH: cell height (in pixels) 

CellW: cell width (in pixels) 


Executing GslnitFixBg16()/GslInitFixBg32() once is sufficient; you need not execute it for every frame. 


See also 
GsSortFixBg16() 
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GslnitGraph 

Initialize the graphics system. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GslnitGraph( 

u_short x_res, Horizontal resolution (256/3820/384/51 2/640) 

u_short y_res, Vertical resolution (240/480 NTSC or 256/512 PAL) 

u_short int7, see Explanation 

u_short dither, Dithering processing flag. 0: OFF, 1: ON 

u_short vram) VRAM mode. O: 16-bit, 1: 24-bit 

Explanation 


Resets libgpu and initializes the libgs graphic system. libgpu settings are maintained by the global variables 
GsDISPENV and GSDRAWENV. The programmer can verify and/or modify libgpu by referencing the 
settings. 


The bits of the int? argument are as follows: 


e Interlace display flag (bit O) 
0: Non-interlace GSNONINTER 
1: Interlace GSINTER 

e Double buffer offset mode (bit 2) 
O: GTE offset GSOFSGTE 
1: GPU offset GsOFSGPU 

e GPU Initialize Parameter (bits 4-5) 
0: ResetGraph(O) GsRESETO 
3: ResetGraph(@) GsSRESETS 


Vertical 480 line non-interlace mode is effective only when a VGA monitor is connected. In 240-line mode, 
the top and bottom 8 lines are almost invisible on home-use TV monitors. For PAL mode, the display 
position should be shifted down by 24 lines. 


The double buffer offset mode is either GTE or GPU offset; when it is GPU, the packet does not include the 
offset value and therefore be handled easily. 











For 24-bit mode, only the memory image display is available and polygon drawing cannot be done. 


Since initialization of the graphic system involves initialization of GSIDMATRIX and GsIDMATRIX2 as well, 
GslnitGraph() must be called prior to all other libgs functions for correct operation. 


See also 
GsInitGraph2() 
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GslInitGraph2 
Initialize the graphics system. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 
Syntax 
void GslnitGraph2( 
u_short x_res, Horizontal resolution (256/320/384/512/640) 
u_short y_res, Vertical resolution (240/480) 
u_short int1, Interlace display flag (bit 0) O: Non-interlace, 1: Interlace 
Double buffer offset mode (bit 2) 0O: GTE offset, 1: GPU offset 
u_short dither, Dithering. O: OFF, 1: ON 
u_short vram) VRAM mode. O: 16-bit, 1: 24-bit 
Explanation 


GsInitGraph2() is different from GslnitGraph() in that the GPU is not initialized COLD. This function is useful 
for changing libgs resolution without affecting screen synchronization. 


Always use GslnitGraph() for the first initialization. 


See also 
GslnitGraph() 
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GsInitVcount 

Initialize vertical retrace counter. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsInitVcount(void) 


Explanation 
Initializes the vertical retrace counter, and starts it. 


See also 
GsClearVcount(), GsGetVcount() 
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GsLinkObject3 

Link an object with PMD data; for GsSortObject3\(). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsLinkObject3( 

u_long *omd, Pointer to the PMD data to be linked 

GsDOBJ3 *obj_base) Pointer to the object structure to be linked 

Explanation 


Links all objects contained in PMD data to a GSDOBUS8 object structure. 
Note: Unlike GsLinkObject4(), it is not possible to select and link a single object in the PMD data. 


See also 
GsSortObject3(), GsLinkObject4() 
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GsLinkObject4 

Link an object to TMD data; for GsSortObject4(). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsLinkObject4( 

u_long tma, Starting address of the TMD data to be linked 

GsDOBU2 “obj_base, Array of the object structure to be linked 

int n) Index of the object to be linked 

Explanation 


Links the n-th object of TMD-format three-dimensional data to a GSDOBJ2 object structure. 


An object linked using this function uses GsSortObject4() to create a packet. 


See also 
GsSortObject4() 
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GsLinkObject5 

Link an object to TMD data; or GsSortObject5\(). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsLinkObject5( 

u_long tmd, Starting address of the TMD data to be linked 

GsDOBUJ5 *obj_base, Array of the object structure to be linked 

int n) Index of the object to be linked 

Explanation 


Links the n-th object of TMD-format three-dimensional data to a GSDOBU5 object structure. 


An object linked using this function uses GsSortObject5() to create a packet. 


See also 
GsSortObject5\() 
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GsMapModelingData 

Map TMD data to real addresses. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSMapModelingData( 

u_long *p) Pointer to starting address of TMD data 

Explanation 


TMD data includes several fields containing addresses of data. During the preparation of TMD data, the 
load addresses of the data are not yet known; therefore, the address fields are stored as offsets from the 
start of the data. GsMapModelingData() changes these offsets into actual addresses after the TMD data 
has been loaded into memory, so that the TMD data may be used. 








A flag is set in the TMD data to indicate when offset addresses have been converted into real addresses. 
Therefore, no side effect occurs even if GsMapModelingData() is called again. 
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GsMulCoord0O 

MATRIX multiplication. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 


void GsMulCoord2( 
MATRIX *m7, MATRIX *m2) Pointers to starting addresses of TMD data 


Explanation 
Multiplies MATRIX m2 by the translation matrix. The results are stored in m3. 


m3 = m1 x m2 


See also 
GsMulCoord2(), GsMulCoord30 
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GsMulCoord2 

MATRIX multiplication. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsMulCoord2( 
MATRIX *m7, MATRIX *m2) Pointers to matrices 


Explanation 
GsMulCoord2 multiplies the MATRIX m2 by the translation matrix m7and stores the result in m2. 


m2 = m1 x m2 


See also 
GsMulCoord0(), GsMulCoord30 
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GsMulCoord3 

MATRIX multiplication. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsMulCoord3( 
MATRIX *m7, MATRIX *m2) Pointers to matrices 


Explanation 
GsMulCoords3 multiplies the MATRIX m2 by the translation matrix m7and stores the result in m2. 


mi=m1xm2 


See also 
GsMulCoord0(), GsMulCoord2() 
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GsPresetObject 

Create a preset packet for a GSDOBJ5-type object. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

u_long *GsPresetObject( 

GsDOBU5 *objp, Pointer to the object to be preset 

u_long *addr) Pointer to starting address of the area in which the preset packet is to be 

prepared. 
Explanation 


Presetting refers to the advance preparation of polygons of all objects as packets. The areas that need not 
be rewritten (e.g., U and V of texture) for each frame are not rewritten, thus ensuring high speed. 








The return value points to the address next to the last preset address, so when presetting the next object, 
preserve the return value and pass it as an argument of the next GsPresetObject(). The return value 
indicates how large an area must be allocated for the preset area. 





A GsDOBU5 type object pointer is exclusively used for presetting. 





Return value 
Pointer that indicates the next to last preset address. 


See also 
GsPrst...() 
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Low-level functions for GsSortObject5uJ\(). 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.1 12/14/98 
Syntax 


PACKET *GsPrst...( 


TMD_P_... *op, Pointer to starting address of TMD data primitives 
VERT *vp, Pointer to starting address of TMD data vertices TMD 
VERT “np, Pointer to starting address of TMD data normals 
PACKET “ok, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 


u_long “scratch) Pointer to starting address of unused scratch pad 


PACKET *GsPrstN...( 


TMD_P_... *op, Pointer to starting address of TMD data primitives 
VERT “vo, Pointer to starting address of TMD data vertices TMD 
PACKET “pk, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 


u_long “scratch) Pointer to starting address of unused scratch pad 


Explanation 
These are low-level functions for GsSortObject5J(). 
To use these functions, they must be registered in GSFCALL5 as low-level functions. 


These functions perform coordinate and perspective transformation, backface clipping, and light source 
calculation for n primitives, create the GPU packet in the buffer, and link it into the OT. There must be two 
preset packets in the buffer per polygon. 





For function types which do not operate on normals within the data (e.g. GsPrstN...), light source 
calculations are not performed, so fewer parameters are passed compared to those function types which 
operate on normals (e.g. GsPrst...), 





Low-level functions in libgs that are supported are shown below. 


Table 9-7: GsPrst...() [have normals] 
Low-level function First arg (op) tyoe Description 








name 

GsPrstF3L TMD_P_F83 Flat triangle (light source calculation) 

GsPrstF3LFG TMD_P_FS3 Flat triangle (light source calculation +FOG) 

GsPrstF3NL TMD_P_F83 Flat triangle 

GsPrstF4L TMD_P_F4 Flat quadrilateral (light source calculation) 

GsPrstF4LFG TMD_P_F4 Flat quadrilateral (light source calculation 
+FOG) 

GsPrstF4NL TMD_P_F4 Flag quadrilateral 

GsPrstG3L TMD_P_G3 Gouraud triangle (light source calculation) 

GsPrstG3LFG TMD_P_G3 Gouraud triangle (light source calculation 
+FOG) 

GsPrstG3NL TMD_P_G3 Gouraud triangle 

GsPrstG4L TMD_P_G4 Gouraud quadrilateral (light source 
calculation) 

GsPrstG4LFG TMD_P_G4 Gouraud quadrilateral (light source 
calculation +FOG) 

GsPrstG4NL TMD_P_G4 Gouraud quadrilateral 
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Low-level function First arg (op) tyoe Description 
name 
GsPrstTF3L TMD_P_TF3 Textured flat triangle 

(light source calculation) 
GsPrstTF3LFG TMD_P_TF3 Textured flat triangle 

(light source calculation +FOG) 
GsPrstTF3NL TMD_P_TF3 Textured flat triangle 
GsPrstTF4L TMD_P_TF4 Textured flat quadrilateral 

(light source calculation) 
GsPrstTF4LFG TMD_P_TF4 Flat quadrilateral 

(light source calculation +FOG) 
GsPrstTF4NL TMD_P_TF4 Textured flat quadrilateral 
GsPrstTG3L TMD_P_TG3 Textured Gouraud triangle 

(light source calculation) 
GsPrstTG3LFG TMD_P_TG3 Textured Gouraud triangle 

(light source calculation +FOG) 
GsPrstTG3NL TMD_P_TG3 Textured Gouraud triangle 
GsPrstTG4L TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation) 
GsPrstTG4LFG TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation +FOG) 
GsPrstTG4NL TMD_P_TG4 Textured Gouraud quadrilateral 
GsPrstF3GL TMD_P_F8G Flat gradation triangle 

(light source calculation) 
GsPrstF3GLFG TMD_P_F8G Flat gradation triangle 

(light source calculation +FOG) 
GsPrstF3GNL TMD_P_F8G Flat gradation triangle 
GsPrstG38GL TMD_P_G3G Gouraud gradation triangle 

(light source calculation) 
GsPrstG3GLFG TMD_P_G3G Gouraud gradation triangle 

(light source calculation +FOG) 
GsPrstG3GNL TMD_P_G3G Gouraud gradation triangle 





Table 9-8: GsPrstN...() [no normals] 








Low-level function First arg (op) tyoe Description 

name 

GsPrstNF3 TMD_P_NF3 Flat triangle 

GsPrstNF4 TMD_P_NF4 Flat quadrilateral 

GsPrstNG3 TMD_P_NG3 Gouraud triangle 

GsPrstNG4 TMD_P_NG4 Gouraud quadrilateral 
GsPrstTNF3 TMD_P_TNF3 Textured flat triangle 
GsPrstTNF4 TMD_P_TNF4 Textured flat quadrilateral 
GsPrstTNG3 TMD_P_TNG3 Textured Gouraud triangle 
GsPrstTNG4 TMD_P_TNG4 Textured Gouraud quadrilateral 





Return value 


Starting address of unused packet area. 


With gradation, each vertex of the TMD polygon has a different RGB value. 


For high speed operation, libgte contains tuned assembly-level low-level functions. 


See also 


GsPresetObject(), GsSortObject5uU() 
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9-66 Extended Graphics Library Functions 


GsScaleScreen 

Scale the screen coordinate system. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Syntax 

void GsScaleScreen( 

SVECTOR *scale) Pointer to the scale factor (12 bit fixed radix point format). Always set the 


factor in relation to the original screen coordinate systems set on 
GsSetView2() and GsSetRefView2(). When ONE (4096) is inserted into 
scale->vx, vy or vz, it returns to the original scale. 


Explanation 
Scales the screen coordinate system against the world coordinates. 


World coordinates are 32-bit values and screen coordinates are 16-bit values. This difference brings about 
problems such as FarClip being close. 


To solve these problems, this function scales the screen coordinates to cover a larger area than world. 


For example, when specifying ONE/2 to vx, vy or vz, the screen coordinate system is expanded to the 
equivalent of 17 bits. However, since the precision is 16 bits, the lower 1 bit is invalid. 














Note: Make sure that the screen coordinate system which has a different scale is not registered to the OT 
with the same scale. For example, before registering an object calculated with the normal scaling screen 
coordinate system to the OT which has already registered an object with a 1/2 screen coordinate system 
scale, it is necessary to shift the excess 1 bit. 





When the scaling matrix set by this function to the external variable GSWSMATRIX, and the screen 
coordinates set by GsSetView2() and GsSetRevView2() to the external variable GSWSMATRIX_ORG are 
defined, the WSMATRIX is held. 
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Extended Graphics Library Functions 9-67 


GsSetAmbient 

Set color and brightness of ambient lighting. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSetAmbient( 

u_long 1, g, b) Ambient color RGB values (0-4095) 

Explanation 


Sets the color and brightness of the ambient lighting in the 3D world. Values for red, green, and blue are 
set independently. A value of 4096 corresponds to normal ambient brightness, O to minimum brightness. 
Values greater than 4096 strengthen that color. For example, 1/1 is 4096 and 1/8 is 4096/8. 
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9-68 Extended Graphics Library Functions 


GsSetClip 


Set drawing clipping area. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 

void GsSetClip( 

RECT *clip) Beginning address of a RECT structure for setting a clipping area 
Explanation 


Sets clipping for drawing. This function is different from GsSetDrawBuffClip() in that its argument can be 
used to specify a clip area. Note that this clipping value is a relative one within the double buffer, and thus 
the clip position doesn’t change if the double buffer is swapped. 


Clipping is done by libgpu. 


See also 
GsSetDrawBuffClip(), GsSetClip2() 
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Extended Graphics Library Functions 9-69 


GsSetClip2 


Set a drawing clipping area. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 

DRAWENV *GsSetClip2( 

RECT “clip) Beginning address of a RECT structure for setting a clipping area 
Explanation 


Sets the clipping rectangle for drawing to the rectangle specified by clip. This function is different from 
GsSetClip() in that the DRAWENV and DISPENV structures are not updated. The return value of 
GsSetClip2() is a pointer to a DRAWENV structure that can be used if necessary to set the system 
DRAWENYV structure using PutDrawEnv(). The global DRAWENV must have been previously specified in 
order for the information in this structure to be valid. 


Note: This clipping rectangle is relative to whichever is the current buffer, even if double-buffering is used. 


Return value 


A pointer to an updated DRAWENV structure (which can be used to update the system DRAWENV 
structure if desired). 


Clipping is done by libgpu. 


See also 
PutDrawEnv(), GsSetClip() 
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9-70 Extended Graphics Library Functions 





GsSetClip2D 

Set two-dimensional clipping. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

GsSetClip2D( 

RECT *rectp) Pointer to the area to be clipped 

Explanation 





Sets the area given by rectp as the area to be clipped. 

When swapping double buffers, clipping occurs in the same relative position in both buffers. 
GsSetDrawBuffClip() must be called in order to validate this setting immediately afterwards. If it is not 
called, the setting is valid from the next frame. 


See also 
GsSetDrawBuffClip() 
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Extended Graphics Library Functions 9-71 


GsSetDrawBuffClip 

Set drawing clipping area. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsSetDrawBuffClip(voic) 
Explanation 
Sets clipping for drawing. The clipping value set by GsSetClip2D\() is set in libgs. 


This value is a relative one within the double buffers, so the clipping position does not change when buffers 
are swapped. 


This function does not execute correctly if GPU drawing is in progress. Use ResetGraph(1) to terminate any 
current drawing process or DrawSync() to wait until the process is completed. 


See also 
GsSetClip2D(), ResetGraph(), DrawSync() 
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9-72 Extended Graphics Library Functions 


GsSetDrawBuffOffset 

Set the drawing offset. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsSetDrawBuffOffset(voic) 


Explanation 


Sets the drawing offset stored in the global variable POSITION. This offset is relative within the double 
buffer, so it is preserved if the buffers are swapped. 


It sets the libgte or libgpu offset, depending on the value of the third argument of GsInitGraph(), either 
GsOFSGPU or GSOFSGTE. 


This function does not execute correctly if GPU drawing is in progress. Use ResetGraph(1) to terminate any 
current drawing process or DrawSync() to wait until the process is completed. 


See also 
ResetGraph(), DrawSync(), GsSetOffset() 
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Extended Graphics Library Functions 9-73 


GsSetFlatLight 


Set a parallel light source. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

void GsSetFlatLight( 

u_int id, Light source number (0, 1, 2) 
GsF_LIGHT “/) Pointer to light source data 
Explanation 


Sets the values for one of up to three parallel light sources. Light source data is specified in the 
GsF_LIGHT structure. 
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9-74 Extended Graphics Library Functions 


GsSetFogParam 

Set the fog parameter. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.A 2.X 12/14/98 

Syntax 


void GsSetFogParam( 
GsFOGPARAM *fogparam) Pointer to a fog parameter structure 


Explanation 


Sets the fog parameter. Fog is valid only in lighting modes 1 and 3. (However, lighting mode 3 is currently 
not supported.) 
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Extended Graphics Library Functions 9-75 


GsSetLightMatrix 
Set a light matrix. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

void GsSetLightMatrix( 

MATRIX *mp) Pointer to matrix 

Explanation 

The three light source vectors and the local screen light matrix mp are multiplied and placed in the GTE. 
When using libgte to do light source calculations, call GsSetLightMatrix() first. 


Depending on the type of model data, some of the GsSortObject...() routines do light source calculations 
(there are no preset light calculations). In this case, also, you must use GsSetLightMatrix() to set a light 
matrix in advance. 


Generally, mp is a local-world matrix. 


See also 
GsSetLightMatrix2() 
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9-76 Extended Graphics Library Functions 


GsSetLightMatrix2 
Set a light matrix. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 

void GsSetLightMatrix2( 

MATRIX *mp) Pointer to matrix 

Explanation 

The three light source vectors and the local screen light matrix mp are multiplied and placed in the GTE. 
When using libgte to do light source calculations, call GsSetLightMatrix() first. 


Depending on the type of model data, some of the GsSortObject...() routines do light source calculations 
(there are no preset light calculations). In this case, also, you must use GsSetLightMatrix2() to set a light 
matrix in advance. 


Generally, mp is a local-world matrix. 


The difference between GsSetLightMatrix() and this function is whether the GTE rotation matrix and the 
parameter mp are destroyed or not. GsSetLightMatrix2() destroys these values, however, 
GsSetLightMatrix2() is faster than GsSetLightMatrix(). 


You must call GsSetLightMatrix() before GsSetLsMatrix(). 








See also 
GsSetLightMatrix(), GsSetLsMatrix() 
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Extended Graphics Library Functions 9-77 


GsSetLightMode 


Set light source mode. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 
void GsSetLightMode( 
int mode) Light source mode value: 
0: Normal lighting 
1: Normal lighting with fog ON 
2: Material lighting (not currently supported) 
3: Material lighting with fog ON (not currently supported) 


Explanation 


Sets the default light source mode. The method of light source calculation can be also set using status bits 
for each object. The setting of the status bit overrides the default setting. 
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9-78 Extended Graphics Library Functions 


GsSetLsMatrix 


Set a local screen matrix. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

void GsSetLsMatrix( 

MATRIX *mp) Pointer to local screen matrix to be set 

Explanation 

Sets a GTE local screen matrix. When you use this function for libgte perspective transform processing, you 
must first set a local screen matrix in libgte. 


For GsSortObject...() calls to perform perspective transformations and use them in libgte, you must first call 
this function. 





See also 
GsSetLightMatrix2() 
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Extended Graphics Library Functions 9-79 


GsSetOffset 


Set an offset. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 

void GsSetOffset( 

long offx, Drawing offset X 
long offy) Drawing offset Y 


Explanation 

Specifies a drawing offset. This function is different from GsSetDrawBuffOffset() in that it sets an offset 
provided as an argument while GsSetDrawBuffOffset() sets a value for the global variable, POSITION. The 
offset to be provided as an argument is a relative offset inside the double buffer. In other words, the double 
buffer base offset is added to the offset provided by the argument. 


Using the GSOFSGPU or GSOFSGTE macro for the third argument of GsInitGraph() determines whether the 
libgte or libgpu offset should be set. 











This function does not execute correctly if GPU drawing is in progress. Use ResetGraph(1) to terminate any 
current drawing process of DrawSync() to wait until the process is completed. 


See also 
GsSetDrawBuffOffset() 
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9-80 Extended Graphics Library Functions 


GsSetOrign 

Set offset that is valid if the screen is switched. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Syntax 

void GsSetOrign( 

long x, Drawing offset X 

long y) Drawing offset Y 

Explanation 


Specifies a drawing offset. This offset value is valid until the GsSetOrign() is called again, unlike 
GsSetOffset(), where the offset value is temporary and becomes invalid when GsSwapDispBuff() and 
GsSetDrawBuffOffset() are called. 


The x, y offset provided is relative inside the double buffer; that is, the double buffer base offset is added to 
the offset provided. 











Note: The third argument of GsInitGraph() determines whether the libgte or libgpu offset should be set 
(either GSOFSGPU or GSOFSGTE ) 


This function does not execute correctly when GPU drawing is in progress. 





See also 
GsInitGraph(), GsSetClip2D() 
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GsSetProjection 

Set the projection plane position. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSetProjection( 

u_long h) Distance (projection) between the viewpoint and projection plane 


Default: 1000 


Explanation 
Sets the distance between the projection plane and the viewpoint. This results in a change in field of view. 


Figure 9-1: Projection 
SCREEN 


_ 


Viewpoint 


The size of the projection plane is specified by (x_res, y_res) in GslnitGraph(). The size of the projection 
plane is constant with respect to the resolution, so the drawing angle is reduced as projection is increased, 
and the drawing angle is increased as projection is decreased. 


See also 
GsInitGraph() 
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9-82 Extended Graphics Library Functions 


GsSetRefView2 


Set world-to-screen matrix. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 


int GsSetRefView2( 
GsRVIEW2 *ov) Pointer to view information 


Explanation 


Calculates GSWSMATRIX using viewpoint information in pv. GSWSMATRIX doesn’t change unless the 
viewpoint is moved, so this function should be called every frame only if the viewpoint is moved, in order for 
changes to be updated. 








It should also be called every frame if the GSRVIEW2 member super is set to anything other than WORLD, 
because even if the other parameters are not changed, if the parameters of the superior coordinate system 
are changed, the viewpoint will have moved. 











Return value 
O on success; 2 on failure. 


See also 
GsSetRefView2L() 
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Extended Graphics Library Functions 9-83 


GsSetRefView2L 

Set viewpoint (high-precision version). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.5 12/14/98 

Syntax 

int GsSetRefView2L( 

GsRVIEW2 *ov) Pointer to viewpoint location information (view/reference point type) 

Explanation 


Calculates GSWSMATRIX using the viewpoint information in pv. GSWSMATRIX doesn’t change unless the 
viewpoint is moved, so this function should be called every frame only if the viewpoint is moved, in order for 
changes to be updated. 








It should also be called every frame if the GSRVIEW2 member super is set to anything other than WORLD, 
because even if the other parameters are not changed, if the parameters of the superior coordinate system 
are changed, the viewpoint will have moved. 











Compared to GsSetRefView2(), GsSetRefView2L() has higher precision: viewpoint wobbling caused by 
insufficient precision is improved. However, its execution time is doubled. 


Return value 
O for successful viewpoint set, 1 for error. 


See also 
GsSetRefView2() 
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9-84 Extended Graphics Library Functions 


GsSetView2 


Set viewpoint. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 


Syntax 

int GsSetView2( 

GsVIEW2 *pv) Pointer to viewpoint position data (matrix form) 
Explanation 

Sets GSWSMATRIX directly. 


If you use GsSetRefView2() to determine the WS matrix from the viewpoint and the focal point, insufficient 
precision may cause errors when you move the viewpoint; it is more effective to use GsSetView2(). 





If the GsVIEW2 super member is anything besides WORLD, you must call this function in each frame in 
which the parent coordinate system parameters are changed. 


If GSIDMATRIX2 is used as the base matrix, then the aspect ratio of the screen is adjusted automatically. 


Return value 
O if successful; 1 if unsuccessful. 


See also 
GsSetRefView2() 
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Extended Graphics Library Functions 9-85 


GsSetWorkBase 

Set address for storing drawing commands. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSetWorkBase( 

PACKET *base_adar) Pointer to an address storing drawing commands 

Explanation 


Sets the memory address for storing drawing primitives generated by functions like GsSortObject...(), 
GsSortSprite(), and GsSortBg(). 


Primitives must be stored at the starting address of a packet area reserved by the user at the beginning of 
processing for each frame. 


See also 
GsSortSprite(), GsSortBg() 
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9-86 Extended Graphics Library Functions 


GsSortBg, GsSortFastBg 
Register BG in the OT. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortBg( 

GsBG “bg, Pointer to BG 

GsOT “otp, Pointer to OT 

u_short pri) Position in OT 


void GsSortFastBg( 


GsBG “bg, Pointer to BG 
GsOT “otp, Pointer to OT 
u_short pri) Position in OT 
Explanation 


Assigns BG indicated by bg to the ordering table indicated by otp. pri refers to the priority of the Sprite in 
the ordering table. The highest priority is zero, with the lowest priority depending on the size of the ordering 
table. Values beyond the ordering table size are clipped to the available maximum value. 











Turning off extension and rotation functions in the bg attributes gives higher-speed processing. 


In GsSortFastBg(), not using enlargement, rotation, and reduction functions results in higher-speed 
processing. The Sprite structure members values mx, my, scalex, scaley, and rotate are ignored. 


See also 
GsSortFixBg16() 
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GsSortBo Fill 

Register a rectangle in the OT. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSortBoxFill( 

GsBOXF *bp, Pointer to GSBOXF 

GsOT “ot, Pointer to OT 

u_short pri) Position in OT 

Explanation 


Assigns a rectangle indicated by bp to the ordering table indicated by ot. 
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9-88 Extended Graphics Library Functions 


GsSortClear 

Register a screen clear command in the OT. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsSortObject( 

u_char r, u_char g, u_char b, Background color RGB values 
GsOT “*otp) Pointer to OT 

Explanation 


Sets a screen clear command at the start of the OT indicated by otp. Should be called after 
GsSwapDispBuff). Note: Actual clearing isn’t executed until GsDrawOt() is used to start drawing. 


See also 
GsSwapDispBuff(), GsDrawOt() 
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GsSortFixBg16, GsSortFixBg32 
Register BG in the OT (high-speed) 


Library Header File Introduced Documentation Date 
libgs. lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortFixBg16( 

GsBG “bg, Pointer to GSBG 

u_long “work, Pointer to work area (primitive area) 

GsOT “otp, Pointer to OT 

u_short pri) Position in OT 


void GsSortFixBg32( 


GsBG “bg, Pointer to GSBG 

u_long “work, Pointer to work area (primitive area) 
GsOT *otp, Pointer to OT 

u_short pri) Position in OT 

Explanation 


These functions perform high-speed BG registration. They are less CPU-intensive than GsSortFastBg(), 
with the following restrictions. 


BG rotation/enlargement/reduction is not possible 

Fixed cell size: 16 for GsSortFixBg16(), 32 for GsSortFixBg32() 
Texture pattern color mode is only 4-bit/8-bit 

Map size is optional 

Scroll is possible (in 1-pixel units) 

Only full-screen 


These functions use the work area to store drawing primitives. The work area uses an unsigned long array; 
this must be initialized beforehand by GslnitFixBg16() or GsInitFixBg32(). These functions do not use the 
packet area (an area set by GsSetWorkBase(). 








See also 
GsSortBg(), GsSetWorkBase() 
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9-90 Extended Graphics Library Functions 


GsSortGLine, GsSortLine 
Register a straight line in the OT. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortGLine( 

GsLINE “Ip, Pointer to GSLINE/GsGLINE 

GsOT “ot, Pointer to OT 

u_short pri) Position in OT 


void GsSortLine( 


GsLINE “Ip, Pointer to GSLINE/GsGLINE 
GsOT “ot, Pointer to OT 

u_short pri) Position in OT 

Explanation 


Assigns the straight line indicated by /p to the ordering table indicated by ot. 
GsSortLine() registers single-color straight lines in OT, and GsSortGLine() graded straight lines in OT. 
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GsSortObject3 

Register an object to the ordering table (for use with GSDOBJ3). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortObject3( 

GsDOBUS *objp, Pointer to an object 

GsOT “otp, Pointer to OT 

int shift) Specifies how many bits the Z value must be shifted to the right when 





assigning an object to the OT 


Explanation 


Performs perspective transformation and light source calculation for a three-dimensional object handled by 
GsDOBUS, and creates a drawing command within the PMD format packet memory. Performs Z-sort of the 
drawing commands generated immediately afterwards and assigns them to the OT indicated by otp. 


The accuracy of Z may be adjusted with the value of shift. The maximum size of the ordering table 
(resolution) is 14 bits, but if this value is set to 12 bits, for example, the shift value must be set at 2 (=14- 
12), so that it will not be larger than the ordering table area. 
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9-92 Extended Graphics Library Functions 





GsSortObject4 

Register an object to the ordering table (for use with GSDOBJ2). 
Library Header File Introduced Documentation Date 
libgs. lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortObject4( 

GsDOBU2 *objp, Pointer to an object 

GsOT “otp, Pointer to OT 

int shift, Specifies how many bits the Z value must be shifted to the right when 

assigning an object to the OT 
u_long “scratch) Pointer to address of scratch pad 
Explanation 


Performs perspective transformation and light source calculation for a three-dimensional object handled by 
GsDOBUJ2, and creates a drawing command within the packet area specified by GsSetWorkBase(). 
Performs Z-sort of the drawing commands generated immediately afterwards and assigns them to the OT 
indicated by ofp. 


The accuracy of Z may be adjusted with the value of shift. The maximum size of the ordering table 
(resolution) is 14 bits. If this value is set to 12 bits, for example, the shift value must be set at 2 (=14-12), so 
that it will not be larger than the ordering table area. 


scratch is the specified scratchpad address used as work when automatic division is being performed. The 
scratchpad runs for 256 words from 0x1 f800000 in cache memory. 


To use the GSOBJ2 member attribute to enable division, perform an OR operation on the macros GsDIV1 
through GsDIV5 (defined in libgs.h). For GSDIV1, a single polygon is divided into four segments of 2 x 2. For 
GsDIV5, a single polygon is divided into 1,024 segments of 32 x 32. 





For a triangle, the scratch area usage is 96 + 88*N, where N is the number of the macro used (GsDIV1 = 1, 
GsDIV2 = 5, etc.) For a quadrilateral, the scratch area used is 120 + 140*N. 


See also 
GsSortObject4J() 
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GsSortObject4J 

Register an object to ordering table (jump table version). 
Library Header File Introduced Documentation Date 
libgs. lib libgs.h 3.2 12/14/98 

Syntax 

void GsSortObject4J( 

GsDOBU2 *objp, Pointer to an object 

GsOT “otp, Pointer to OT 

int shift, Specifies how many bits the Z value must be shifted to the right when 

assigning an object to the OT 
u_long “scratch) Pointer to the address of the scratch pad 
Explanation 





Same functionality as GsSortObject4(), when all the low-level functions have been registered. Allows 
programmer to increase code efficiency by not calling unnecessary low-level functions (up to 40 kbytes can 
be saved.) 





To do this, test which low-level routines are being called by prepending ‘dmy’ to the function names in 
GsFCALL4, the reference function table. The names of all functions called are printed out; for those 
functions, delete ‘dmy’, and only those functions used will be llinked in. 


See also 
GsSortObject4(), GsSortObject5J() 
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GsSortObject5 

Register an object to the ordering table (for use with GSDOBJ5). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 

Syntax 

void GsSortObject5( 

GsDOBU5 “objp, Pointer to an object 

GsOT “otp, Pointer to OT 

int shift, Specifies how many bits the Z value must be shifted to the right when 

assigning an object to the OT 
u_long “scratch) Pointer to the address of the scratch pad 
Explanation 


Performs transparency transformation and light source calculation for a three-dimensional object to be 
handled by GSDOBU5. It creates in the preset packet area drawing commands that do not divide, and in 
the packet area specified by GsSetWorkBase() those drawing commands that do divide. Performs Z-sort of 
the drawing commands generated immediately afterwards and assigns them to the OT indicated by otp. 








The accuracy of Z may be adjusted using the shift value. The maximum size of the ordering table 
(resolution) is 14 bits. If this value is set to 12 bits, for example, the shift value must be set at 2 (=14-12), so 
that it will not be larger than the ordering table area. 


scratch is the specified scratchpad address used as work when automatic division is being performed. (The 
scratchpad is 256 words starting from Ox1f800000 in cache memory.) To use GSdOBU5.attribute to 
enable division, perform an OR operation on the macros GsDIV1-GsDIV5 of libgs.h. For GsDIV1, a single 
polygon is divided into four segments of 2 x 2. For GsDIV5, a single polygon is divided into 1, 024 
segments of 32 x 32. 


For a triangle, the scratch area usage is 96 + 88*N, where N is the number of the macro used (GsDIV1 = 1, 
GsDIV2 = 5, etc.) For a quadrilateral, the scratch area used is 120 + 140*N. 


See also 
GsSortObject5J() 
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GsSortObject5J 

Register an object to the ordering table (jump table version). 
Library Header File Introduced Documentation Date 
libgs. lib libgs.h 3.2 12/14/98 

Syntax 

void GsSortObject5J( 

GsDOBUJ5 *objp, Pointer to an object 

GsOT “otp, Pointer to OT 

int shift, Specifies how many bits the Z value must be shifted to the right when 

assigning an object to the OT 
u_long “scratch) Pointer to the address of the scratch pad 
Explanation 





Same functionality as GsSortObject5(), when all the low-level functions have been registered. Allows 
programmer to increase code efficiency by not calling unnecessary low-level functions (up to 40 kbytes can 
be saved.) 





To do this, test which low-level routines are being called by prepending ‘dmy’ to the function names in 
GsFCALL5, the reference function table. The names of all functions called are printed out; for those 
functions, delete ‘dmy’, and only those functions used will be llinked in. 





See also 
GsSortObject5(), GsSortObject4J() 
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GsSortOt 

Insert an OT into another OT. 
Library Header File Introduced Documentation Date 
libgs. lib libgs.h 3.3 12/14/98 

Syntax 

GsOT *GsSortOt( 

GsOT *ot_src, Pointer to source OT 

GsOT *ot_dest) Pointer to destination OT 

Explanation 


Inserts the OT given by ot_src into the OTZ location within ot_dest. 
The OTZ value used at this time is calculated as follows: 


OTZ = ot_src->point - ot_dest ->offset 


Return value 
Pointer to the integrated OT. 


See also 
GsClearOt(), GsDrawOt(), GsCutOt() 
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GsSortPoly 

Register a polygon drawing primitive in the OT. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSortPoly( 

void “prim, Pointer to drawing primitive 

GsOT “ot, Pointer to OT 

u_short pri) Location in OT 

Explanation 


Assigns the drawing primitive prim to the ordering table ot. Corresponds to libgpu drawing primitives 
(POLY_....). 


libgs requires no double buffering, since the contents of the primitive structure are copied in the packet 
generation area. Drawing coordinate values match the drawing coordinate system handled by libgs. 
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GsSortSprite, GsSortFastSprite, GsSortFlipSprite 
Register a Sprite in the OT. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 

void GsSortSprite( 

GsSPRITE “sp, Pointer to a Sprite 

GsOT “otp, Pointer to OT 

u_short pri) Position in OT 


void GsSortFastSprite( 


GsSPRITE “sp, Pointer to a Sprite 
GsOT “otp, Pointer to OT 
u_short pri) Position in OT 


void GsSortFlipSprite( 


GsSPRITE “sp, Pointer to a Sprite 
GsOT “otp, Pointer to OT 
u_short pri) Position in OT 
Explanation 


Assigns the sprite sp to the ordering table otp. 


pri refers to the priority of the Sprite in the ordering table. The highest priority value is zero, with the lowest 
value depending on the size of the ordering table. Values beyond the size of the ordering table are clipped 
to the maximum ordering table value. 





GsSortFastSprite(provides high-speed processing, though enlargement, rotation, and reduction cannot be 
used. The Sprite structure members nx, my, scalex, scaley, and rotate are ignored. 


GsSortFlipSprite() does not use the enlargement / rotation / reduction functions, and only supports flipping. 


Performing enlargement or rotation destroys the GTE rotation matrix. 
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GsSwapDispBuffer 

Swaps double buffers. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 2.X 12/14/98 

Syntax 


void GsSwapDispBuffer(voic) 


Explanation 


Exchanges the display buffer with the drawing buffer according to data set by GsDefDispBuff(). Normally, 
swapping is done immediately after beginning vertical blanking. This function 


Sets display starting address 
Cancels blanking 

Sets double buffer index 

Switches two-dimensional clipping 
Sets libgte or libgpu offset 

Sets libgs offset 


Note: Using the GSOFSGPU or GSOFSGTE macro for the third argument of GsInitGraph() determines 
whether the libgte or libgpu offset should be set. 





This function does not execute correctly when GPU drawing is in progress, so it is necessary to call this 
function after terminating drawing using ResetGraph (1). 


See also 
GsDefDispBuff() 
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GsTMDdiv... 

Low-level functions for GsSortObject4J() (performs fixed division). 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 4.1 12/14/98 

Syntax 

PACKET *GsTMDdiv...( 

TMD_P_... *op, Pointer to starting address of TMD data primitives 

VERT “vp, Pointer to starting address of TMD data vertices TMD 

VERT “np, Pointer to starting address of TMD data normals 

PACKET “ok, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 


DIVPOLYGON... “divp) Pointer to DIVPOLYGONS or DIVPOLYGON4 


PACKET *GsTMDdivN...( 


TMD_P_... *op Pointer to starting address of TMD data primitives 
VERT “vp, Pointer to starting address of TMD data vertices TMD 
PACKET “pk, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 

DIVPOLYGON... “divp) Pointer to DIVPOLYGONS or DIVPOLYGON4 
Explanation 


These are low-level functions for GsSortObject4J().To be used, they must be registered in GSFCALL4 as 
low-level functions. 





These functions perform fixed division based on the number of divisions (GSNDIV). 


These functions perform polygon division (based on the value of GSNDIV), coordinate and perspective 
transformation, backface clipping, and light source calculation for n primitives, complete the GPU packet in 
the buffer, and link it into the OT. 


ndiv=1: 2x2 division 
ndiv=2: 4x4 division 
ndiv=3: 8x8 division 
ndiv=4: 16x16 division 
ndiv=5: 32x82 division 


For function types which do not operate on normals within the data (e.g. GSTMDdivwN...), light source 
calculations are not performed so fewer parameters are passed compared to those function types which 
operate on normals (e.g. GSTMDdiv...), 


Low-level functions in libgs that support fixed division are shown below. 
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Table 9-9: GSTMDdiv...() [have normals] 


Extended Graphics Library Functions 9-101 








Low-level function First arg (op) Description 
name type 
GsTMDdivF3L TMD_P_F3 Flat triangle (light source calculation) 
GsTMDdivF3LB TMD_P_F3 Flat triangle (light source calculation + 2face) 
GsTMDdivF3LFG TMD_P_F3 Flat triangle (light source calculation +FOG) 
GsTMDdivF3LFGB TMD_P_F3 Flat triangle (light source calculation +FOG + 
2face) 
GsTMDdivF3NL TMD_P_F3 Flat triangle 
GsTMDdivF3NLB TMD_P_F3 Flat triangle (2face) 
GsTMDdivF4L TMD_P_F4 Flat quadrilateral (light source calculation) 
GsTMDdivF4LB TMD_P_F4 Flat quadrilateral (light source calculation + 
2face) 
GsTMDdivF4LFG TMD_P_F4 Flat quadrilateral (light source calculation 
+FOG) 
GsTMDdivF4LFGB TMD_P_F4 Flat quadrilateral (light source calculation 
+FOG + 2face) 
GsTMDdivF4NL TMD_P_F4 Flag quadrilateral 
GsTMDdivF4NLB TMD_P_F4 Flag quadrilateral (2face) 
GsTMDdivG3L TMD_P_G3 Gouraud triangle (light source calculation) 
GsTMDdivG3LB TMD_P_G3 Gouraud triangle (light source calculation + 
2face) 
GsTMDdivG3LFG TMD_P_G3 Gouraud triangle (light source calculation 
+FOG) 
GsTMDdivG3LFGB = TMD_P_G3 Gouraud triangle (light source calculation 
+FOG + 2face) 
GsTMDdivG3NL TMD_P_G3 Gouraud triangle 
GsTMDdivG3NLB TMD_P_G3 Gouraud triangle (2face) 
GsTMDdivG4L TMD_P_G4 Gouraud quadrilateral (light source 
calculation) 
GsTMDdivG4LB TMD_P_G4 Gouraud quadrilateral (light source 
calculation + 2face) 
GsTMDdivG4LFG TMD_P_G4 Gouraud quadrilateral (light source 
calculation +FOG) 
GsTMDdivG4LFGB TMD_P_G4 Gouraud quadrilateral (light source 
calculation +FOG + 2face) 
GsTMDdivG4NL TMD_P_G4 Gouraud quadrilateral 
GsTMDdivG4NLB TMD_P_G4 Gouraud quadrilateral (2face) 
GsTMDdivTFSL TMD_P_TFS Textured flat triangle 
(light source calculation) 
GsTMDdivTF3LB TMD_P_TF8 Textured flat triangle 
(light source calculation + 2face) 
GsTMDdivTF3LFG TMD_P_TF8 Textured flat triangle 
(light source calculation +FOG) 
GsTMDdivIFSLFGB TMD_P_TF3 Textured flat triangle 
(light source calculation +FOG + 2face) 
GsTMDdivTF3NL TMD_P_TF8 Textured flat triangle 
GsTMDdivTF3NLB TMD_P_TF3 Textured flat triangle (2face) 
GsTMDdivTF4L TMD_P_TF4 Textured flat quadrilateral 
(light source calculation) 
GsTMDdivTF4LB TMD_P_TF4 Textured flat quadrilateral 
(light source calculation + 2face) 
GsTMDdivTF4LM TMD_P_TF4 Textured flat quadrilateral 
(light source calculation +mip-map) 
GsTMDdivTF4LFG TMD_P_TF4 Textured flat quadrilateral 
(light source calculation +FOG) 
GsTMDdivIF4LFGB TMD_P_TF4 Textured flat quadrilateral 
(light source calculation +FOG + 2face) 
GsTMDdivIF4LFGM  TMD_P_TF4 Textured flat quadrilateral 


(light source calculation +FOG-+mip-map) 
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Low-level function First arg (op) Description 
name type 
GsTMDdivTF4NL TMD_P_TF4 Textured flat quadrilateral 
GsTMDdivTF4NLB TMD_P_TF4 Textured flat quadrilateral (2face) 
GsTMDdivTF4NLM TMD_P_TF4 Textured flat quadrilateral 

(mip-map) 
GsTMDdivTG3L TMD_P_TG3 Textured Gouraud triangle 

(light source calculation) 
GsTMDdivTG3LB TMD_P_TG3 Textured Gouraud triangle 

(light source calculation + 2face) 
GsTMDdivTG3LFG TMD_P_TG3 Textured Gouraud triangle 

(light source calculation +FOG) 
GsTMDdivTG3LFGB + TMD_P_TG3 Textured Gouraud triangle 

(light source calculation +FOG + 2face) 
GsTMDdivTG3NL TMD_P_TG3 Textured Gouraud triangle 
GsTMDdivTG3NLB TMD_P_TG3 Textured Gouraud triangle (2face) 
GsTMDdivTG4L TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation) 
GsTMDdivTG4LB TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation + 2face) 
GsTMDdivTG4LM TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation +mip-map) 
GsTMDdivTG4LFG TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation +FOG) 
GsTMDdivTG4LFGB TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation +FOG + 2face) 
GsTMDdivTG4LFGM TMD_P_TG4 Textured Gouraud quadrilateral 

(light source calculation +FOG + mip-map) 
GsTMDdivTG4NL TMD_P_TG4 Textured Gouraud quadrilateral 
GsTMDdivTG4NLB TMD_P_TG4 Textured Gouraud quadrilateral (2face) 
GsTMDdivTG4NLM  TMD_P_TG4 Textured Gouraud quadrilateral 


(mip-map) 
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Table 9-10: GSTMDdivN...() [no normals] 
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Low-level function First arg (op) Description 
name type 
GsTMDdivNF3 TMD_P_NF3 Flat triangle 
GsTMDdivNF38B TMD_P_NF3 Flat triangle (2face) 
GsTMDdivNF4 TMD_P_NF4 Flat quadrilateral 
GsTMDdivNF4B TMD_P_NF4 Flat quadrilateral (2face) 
GsTMDdivNG3 TMD_P_NG3 Gouraud triangle 
GsTMDdivNG3B TMD_P_NG3 Gouraud triangle (2face) 
GsTMDdivNG4 TMD_P_NG4 Gouraud quadrilateral 
GsTMDdivNG4B TMD_P_NG4 Gouraud quadrilateral (2face) 
GsTMDdivTNF3 TMD_P_TNF3 Textured flat triangle 
GsTMDdivTNF38B TMD_P_TNF3 Textured flat triangle (2face) 
GsTMDdivTNF4 TMD_P_TNF4 Textured flat quadrilateral 
GsTMDdivTNF4B TMD_P_TNF4 Textured flat quadrilateral (2face) 
GsTMDdivTNF4M TMD_P_TNF4 Textured flat quadrilateral 
(mip-map) 
GsTMDdivTNG3 TMD_P_TNG3 Textured Gouraud triangle 
GsTMDdivTNG3B TMD_P_TNG3 Textured Gouraud triangle (2face) 
GsTMDdivING4 TMD_P_TNG4 Textured Gouraud quadrilateral 
GsTMDdivTNG4B TMD_P_TNG4 Textured Gouraud quadrilateral (2face) 
GsTMDdivING4M TMD_P_TNG4 Textured Gouraud quadrilateral 


(mip-map) 





Number of divisions is specified in the GSDOBUJ2 attribute. 


Return value 
Starting address of unused packet area. 


See also 
GsSortObject4J() 
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GsTMDfast..., GSTMDfastN... 


Low-level functions for GsSortObject4uJ(). 


Library Header File Introduced Documentation Date 
libgte.lib libgte.h 4.1 12/14/98 
Syntax 
PACKET *GsTMDfast...( 
TMD_P_... *op, Pointer to starting address of TMD data primitives 
VERT *vp, Pointer to starting address of TMD data vertices TMD 
VERT “np, Pointer to starting address of TMD data normals 
PACKET “pk, Pointer to top address of GPU packet buffer 
int n, Number of primitives 
int shift, OT shift bit 
GsOT “ot, Pointer to GSOT 
u_long “scratch) Pointer to starting address of unused scratch pad 


PACKET *GsTMDfastN...( 


TMD_P_... *op, Pointer to starting address of TMD data primitives 
VERT “vp, Pointer to starting address of TMD data vertices TMD 
PACKET “pk, Pointer to top address of GPU packet buffer 

int n, Number of primitives 

int shift, OT shift bit 

GsOT “ot, Pointer to GSOT 

u_long “scratch) Pointer to starting address of unused scratch pad 
Explanation 


These are low-level functions for GsSortObject4J(). They are tuned assembly-level functions for high speed 
operation in libgte. 





To be used, they must be registered in GSFCALL4 as low-level functions. 


These functions perform coordinate and perspective transformation, backface clipping, and light source 
calculation for n primitives, complete the GPU packet in the buffer, and link it into the OT. 


For low-level functions that provide material attenuation, the lighting mode must be “material ON.” This 
attenuates the brightness during light source calculation based on the parameter which is provided in the 
attribute of GSDOBJ2. 


For low-level functions that FLIP, the direction of the normal clip is reversed. 





For function types which do not operate on normals within the data (e.g. GSTMDfastN...), light source 
calculations are not performed so fewer parameters are passed compared to those function types which 
operate on normals (e.g. GSTMDfast...), 





Low-level functions supported in libgs are shown below. 
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Table 9-11: GSTMDfast...() [have normals] 
Low-level function name First arg (op) type Description 


















































GsTMDfastF3L TMD_P_F3 Flat triangle 

(light source calculation) 
GsTMDfastF3LB TMD_P_F3 Flat triangle 

(light source calculation + 2face) 
GsTMDfastF3LFG TMD_P_F3 Flat triangle 

(light source calculation +FOG) 
GsTMDfastF3LFGB TMD_P_F3 Flat triangle (light source calculation +FOG + 

2face) 
GsTMDfastF3NL TMD_P_F3 Flat triangle 
GsTMDfastF3NLB TMD_P_F3 Flat triangle (2face) 
GsTMDfastF4L TMD_P_F4 Flat quadrilateral 

(light source calculation) 
GsTMDfastF4LB TMD_P_F4 Flat quadrilateral 

(light source calculation + 2face) 
GsTMDfastF4LFG TMD_P_F4 Flat quadrilateral 

(light source calculation +FOG) 
GsTMDfastF4LFGB TMD_P_F4 Flat quadrilateral 

(light source calculation +FOG + 2face) 
GsTMDfastF4NL TMD_P_F4 Flag quadrilateral 
GsTMDfastF4NLB TMD_P_F4 Flag quadrilateral 

(2face) 
GsTMDfastG3L TMD_P_G3 Gouraud triangle 

(light source calculation) 
GsTMDfastG3LB TMD_P_G3 Gouraud triangle 

(light source calculation + 2face) 
GsTMDfastG3LFG TMD_P_G3 Gouraud triangle 

(light source calculation +FOG) 
GsTMDfastG3LFGB TMD_P_G3 Gouraud triangle 

(light source calculation +FOG + 2face) 
GsTMDfastG3NL TMD_P_G3 Gouraud triangle 
GsTMDfastG3NLB TMD_P_G3 Gouraud triangle 

(2face) 
GsTMDfastG4L TMD_P_G4 Gouraud quadrilateral (light source calculation) 
GsTMDfastG4LB TMD_P_G4 Gouraud quadrilateral (light source calculation + 

2face) 
GsTMDfastG4LFG TMD_P_G4 Gouraud quadrilateral (light source calculation 

+FOG) 
GsTMDfastG4LFGB TMD_P_G4 Gouraud quadrilateral (light source calculation 

+FOG + 2face) 
GsTMDfastG4NL TMD_P_G4 Gouraud quadrilatera 
GsTMDfastG4NLB TMD_P_G4 Gouraud quadrilateral (2face) 
GsTMDfastTF3L TMD_P_TF3 Textured flat triangle 

(light source calculation) 
GsTMDfastTF3LB TMD_P_TF3 Textured flat triangle 

(light source calculation + 2face) 
GsTMDfastTF3LFG TMD_P_TF3 Textured flat triangle 

(light source calculation +FOG) 
GsTMDfastTF3LFGB TMD_P_TF3 Textured flat triangle 

(light source calculation +FOG + 2face) 
GsTMDfastTF3NL TMD_P_TF3 Textured flat triangle 
GsTMDfastTF3NLB TMD_P_TF3 Textured flat triangle (2face) 
GsTMDfastTF4L TMD_P_TF4 Textured flat quadrilateral 

(light source calculation) 
GsTMDfastTF4LB TMD_P_TF4 Textured flat quadrilateral 

(light source calculation + 2face) 
GsTMDfastTF4LM TMD_P_TF4 Textured flat quadrilateral 

(light source calculation +mip-map) 
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Low-level function name 


First arg (op) type 


Description 





GsTMDfastTF4LFG 
GsTMDfastTF4LFGB 
GsTMDfastTF4LFGM 
GsTMDfastTF4NL 
GsTMDfastTF4NLB 
GsTMDfastTF4NLM 
GsTMDfastTG3L 
GsTMDfastTG8L_FLIP 
GsTMDfastTG3LB 
GsTMDfastTG3LFG 
GsTMDfastT G3LFG_FLIP 
GsTMDfastTG8LFGB 
fastT G3NL 
fastT G3NL_FLIP 


D 

D 
GsTMDfastTG3NLB 

DfastTG4L 








GsTMDfastTG4LB 








GsTMDfastTG4LM 
GsTMDfastTG4LFG 
GsTMDfastTG4LFGB 
GsTMDfastTG4LFGM 
GsTMDfastTG4NL 


GsTMDfastTG4NLB 
GsTMDfastTG4NLM 





GsTMDfastF38GL 


GsTMDfastF3GLFG 


GsTMDfastF3GNL 
GsTMDfastG3GL 


GsTMDfastG3GLFG 


GsTMDfastG3GNL 
GsTMDfastF4GL 


GsTMDfastF4GLFG 


GsTMDfastF4GNL 
GsTMDfastG4GL 








GsTMDfastG4GLFG 
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TMD_P_TF4 
TMD_P_TF4 
TMD_P_TF4 
TMD_P_TF4 
TMD_P_TF4 
TMD_P_TF4 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 
TMD_P_TG3 


TMD_P_TG3 
TMD_P_TG4 





TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_TG4 
TMD_P_F3G 
TMD_P_F3G 


TMD_P_F3G 
TMD_P_G3G 


TMD_P_G38G 





TMD_P_G3G 
TMD_P_F4G 


TMD_P_F4G 


TMD_P_F4G 
TMD_P_G4G 


TMD_P_G4G 


(light source calculat 
(light source calculat 


(light source calculat 





(mio-map) 
(light source calculat 


(light source calculat 


(light source calculat 


(light source calculat 





(light source calculat 


Textured Gouraud tri 


Textured Gouraud tr 


Textured Gouraud tri 


Textured Gouraud tri 
Textured Gouraud tri 
Textured Gouraud tri 
(light source calculati 
Textured Gouraud tri 


Textured Gouraud tri 


Textured Gouraud tri 


Textured flat quadrilateral 


ion +FOG) 


Textured flat quadrilateral 


ion +FOG + 2face) 


Textured flat quadrilateral 


ion +FOG+mip-map) 


Textured flat quadrilateral 
Textured flat quadrilateral (2face) 
Textured flat quadrilateral 


angle 
ion) 
angle 
ion + FLIP) 
angle 
on + 2face) 
angle 
ion +FOG) 
angle 
ion +FOG + FLIP) 
angle 
ion +FOG + 2face) 
angle 
iangle (FLIP) 

angle (2face) 





Textured Gouraud quadrilateral 


(light source calculat 
(light source calculat 
(light source calculat 
(light source calculat 


(light source calculat 








= 


ight source calculat 


ion) 


Textured Gouraud quadrilateral 


ion + 2face) 


Textured Gouraud quadrilateral 


ion +mip-map) 


Textured Gouraud quadrilateral 


ion +FOG) 


Textured Gouraud quadrilateral 


ion +FOG + 2face) 


Textured Gouraud quadrilateral 





ion +FOG + mip-map) 


Textured Gouraud quadrilateral 
Textured Gouraud quadrilateral (2face) 
Textured Gouraud quadrilateral 


(mip-map) 


Flat gradation triangle 


= 


(light source calculat 


= 


ight source calculat 


= 


ight source calculat 


Flat gradation quadri 
(light source calculat 
Flat gradation quadri 
(light source calculat 
Flat gradation quadri 


= 


ight source calculat 








= 


ight source calculat 


ight source calculati 
Flat gradation triangle 


Flat gradation triangle 
Gouraud gradation triangle 


on) 


ion + FOG) 


ion) 


Gouraud gradation triangle 


ion + FOG) 


Gouraud gradation triangle 


lateral 

ion) 

lateral 

ion + FOG) 
lateral 


Gouraud gradation quadrilateral 


ion) 


Gouraud gradation quadrilateral 





ion + FOG) 
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Low-level function name First arg (op) type Description 
GsTMDfastG4GNL TMD_P_G4G Gouraud gradation quadrilateral 
GsTMDfastF3M TMD_P_F3 Flat triangle 

(light source + material attenuation) 
GsTMDfastF3MFG TMD_P_F3 Flat triangle 

(light source + FOG + material attenuation) 
GsTMDfastF4M TMD_P_F4 Flat quadrilateral 

(light source + material attenuation) 
GsTMDfastF4MFG TMD_P_F4 Flat quadrilateral 

(light source + FOG + material attenuation) 
GsTMDfastG3M TMD_P_G3 Gouraud triangle 

light source + material attenuation) 
GsTMDfastG3MFG TMD_P_G3 Gouraud triangle 

(light source + FOG + material attenuation) 
GsTMDfastG4M TMD_P_G4 Gouraud quadrilateral 

(light source + material attenuation) 
GsTMDfastG4MFG TMD_P_G4 Gouraud quadrilateral 

(light source + FOG + material attenuation) 
GsTMDfastTF3M TMD_P_TF3 Textured flat triangle 

(light source + material attenuation) 
GsTMDfastTF3MFG TMD_P_TF3 Textured flat triangle 

(light source + FOG + material attenuation) 
GsTMDfastTF4M TMD_P_TF4 Textured flat quadrilateral 

(light source + material attenuation) 
GsTMDfastTF4AMFG TMD_P_TF4 Textured flat quadrilateral 

(light source + FOG + material attenuation) 
GsTMDfastTG3M TMD_P_TG3 Textured Gouraud triangle 

(light source + material attenuation) 
GsTMDfastTG3MFG TMD_P_TG3 Textured Gouraud triangle 

(light source + FOG + material attenuation) 
GsTMDfastTG4M TMD_P_TG4 Textured Gouraud quadrilateral 

(light source + material attenuation) 
GsTMDfastTG4MFG TMD_P_TG4 Textured Gouraud quadrilateral 





(light source + FOG + material attenuation) 





Table 9-12: GSTMDfastN...() [no normals] 








Low-level function First arg (op) Description 

name type 

GsTMDfastNF3 TMD_P_NF3 Flat triangle 

GsTMDfastNF3B TMD_P_NF3 Flat triangle (2face) 

GsTMDfastNF4 TMD_P_NF4 Flat quadrilateral 

GsTMDfastNF4B TMD_P_NF4 Flat quadrilateral (2face) 
GsTMDfastNG3 TMD_P_NG3 Gouraud triangle 

GsTMDfastNG3B TMD_P_NG3 Gouraud triangle (2face) 
GsTMDfastNG4 TMD_P_NG4 Gouraud quadrilateral 
GsTMDfastNG4B TMD_P_NG4 Gouraud quadrilateral (2face) 
GsTMDfastTNF3 TMD_P_TNF3 Textured flat triangle 
GsTMDfastTNF3B TMD_P_TNF3 Textured flat triangle (2face) 
GsTMDfastTNF4 TMD_P_TNF4 Textured flat quadrilateral 
GsTMDfastTNF4B TMD_P_TNF4 Textured flat quadrilateral (2face) 
GsTMDfastTNF4M TMD_P_TNF4 Textured flat quadrilateral (mip-map) 
GsTMDfastTNG3 TMD_P_TNG3 Textured Gouraud triangle 
GsTMDfastTNGS_FLIP TMD_P_TNG3 Textured Gouraud triangle (FLIP) 
GsTMDfastTNG3B TMD_P_TNG3 Textured Gouraud triangle (2face) 
GsTMDfastTNG4 TMD_P_TNG4 Textured Gouraud quadrilateral 
GsTMDfastTNG4B TMD_P_TNG4 Textured Gouraud quadrilateral (2face) 
GsTMDfastTNG4M TMD_P_TNG4 Textured Gouraud quadrilateral (mip-map) 








With gradation, each vertex of the TMD polygon has a different RGB value. 
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Return value 
Starting address of unused packet area. 


See also 
GsSortObject4J() 
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Macros 





GsClearDispArea 


Clears screen. 


Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.0 12/14/98 


Syntax 


GsClearDispArea( 
u_char, u_char g, u_char b) Background color RGB values 


Explanation 
The display area is cleared using IO. 


Unlike GsSortClear(), a clear command is issued when GsClearDispArea() is called. 


See also 
GsSortClear() 
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GsincFrame 

Updates the frame ID. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.2 12/14/98 

Syntax 


GsIncFrame() 


Explanation 


GslncFrame() is a macro called from within GsSwapDispBuff(). It increments the global variable PSDCNT 
by 1. PSDCNT is 32 bits in length, and restarts at 1 rather than O when it overflows. 


PSDCNT is used by GsGetLw(),GsGetLs(),GsGetLws() when determining the validity of the matrix cache. 


If you are not using GsSwapDispBuff() to swap double buf you must call GslncFrame to swap the buffers 
when you use GsGetLw(), GsGetLs(), and GsGetLws(). 


Use GsDefDispBuff() to establish settings the first time. 


See also 
GsGetLw(), GsGetLs(), GsGetLws(), GsSwapDispBuff() 
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GsSetAzwh 

Sets conditions for active subdivision. 
Library Header File Introduced Documentation Date 
libgs.lib libgs.h 3.3 12/14/98 

Syntax 

void GsSetAzwh( 

int z, Critical near z value for activate subdivision 

short w, short h) Size of polygon within subdivision routine at which no more subdivision will 

be done 
Explanation 


Sets the conditions for active subdivision. 


z is the near z value for the start of the subdivision fragmentation and w, h is the polygon size for halting the 
subdivision. 


See also 
GsA4Div...() 
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External Variables 





Table 9-13: List of External Variables 








Name of external variable Type Description 
CLIP2 RECT Two-dimensional clipping area. 
Can be set with GsSetClip2D() 
PSDBASEX[2] short Double buffer origin (X coordinate) 
Set with GsDefDispbuff() 
PSDBASEY [2] short Double buffer origin (Ycoordinate) 
Set with GsDefDispbuff() 
PSDIDX short Double buffer index 
PSDCNT u_long Incremented with each frame switch 
POSITION _GsPOSITION Two-dimensional offset 
GsDRAWENV DRAWENV Gs draw environment 
GsDISPENV DISPENV Gs display environment 
GsWSMATRIX MATRIX Gs world-to-screen matrix 
Set with GsSetRefView2(), etc. 
GsLIGHT_MODE int Default light mode 
HWDO long Horizontal resolution 
VWDO long Vertical resolution 
GsLIGHTWSMATRIX MATRIX Gs light matrix. 
Set with GsSetFlatLight() 
GsIDMATRIX MATRIX Unit matrix 
GsIDMATRIX2 MATRIX Unit matrix (includes aspect 
conversion) 
GsLIGHT_FUNC Function pointer Pointer to default light-source 


calculation routines used by 
GsDOBJ1, GSDOBJ2 


GsOUT_PACKET_P u_long Pointer for saving start of packet area. 
Set with GsSetWorkBase() 

GsMATE_C u_long Result of decoding attribute 
(attenuation coefficient) 

GsLMODE u_long Result of decoding attribute 
(Light mode) 

GsLIGNR u_long Result of decoding attribute 
(Ignore light) 

GsLIOFF u_long Result of decoding attribute 
(No shading) 

GsZOVER u_long Result of decoding attribute 
(nearZ) 

GsBACKC u_long Result of decoding attribute 
(Two-sided polygons) 

GsNDIV u_long Result of decoding attribute 
(Number of divisions) 

GsTRATE u_long Result of decoding attribute 
(Semi-transparency rate) 

GsTON u_long Result of decoding attribute 
(Semi-transparency) 

GsDISPON u_long Result of decoding attribute 
(Display ON/OFF) 

GsADIVH short Condition for active automatic 


divisions: Vertical size 

Set with GsSetAzwh(z,w,h) 
GsADIVW short Condition for active automatic 

divisions: Horizontal size 

Set with GsSetAzwh(z,w,h) 


Run-Time Library Reference 


Extended Graphics Library External Variables 9-113 





Name of external variable Type Description 





GsADIVZ long Condition for active automatic 
divisions: Z value 
Set with GsSetAzwh(z,w,h) 
GsFCALL5 Structure Function table for GsSortObject5J() 
GsFCALL4 Structure Function table for GsSortObject4J() 
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StSetMask 
StSetRing 
StSetStream 
StUnSetRing 


Run-Time Library Reference 


10-55 
10-56 
10-57 
10-58 


CD/Streaming Library Structures 10-3 


CdlATV 
Audio attenuation structure. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 8/9/99 
Structure 
typedef struct { 
u_char va/0; CD (L) --> SPU (L) 
u_char va/7; CD (L) --> SPU (R) (CD left sound transferred to right) 
u_char val2; CD (R) --> SPU (R) 
u_char val3; CD (R) --> SPU (L) (CD right sound transferred to left) 
} CdlATV; 
Explanation 


Sets CD audio volume (consisting of CD-DA audio and CD-XA audio). 

Valo - val3 can range from O (minimum volume) to 128 (maximum volume). 

For adjusting normal stereo volume, set the L channel volume in valO and the R channel volume in val2. 
Valland val3 should be set to 0. 


See also 
CdMix() 
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CdIFILE 
ISO-9660 file system file descriptor. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 
Structure 
typedef struct { 
CdILOC pos; File position 
u_long size; File size 
char name/76]; File name 
} CdIFILE; 
Explanation 


Position and size of ISO-9660 CD-ROM file. 


See also 
CdSearchFile() 
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CdIFILTER 
ADPCM channel. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.0 12/14/98 
Structure 
typedef struct { 
u_char file; File ID 
u_char chan; Channel ID 
u_short pad; System reserved 
} CdIFILTER; 
Explanation 


Defines a multi-channel ADPCM play channel. Use CdlSetfilter command of CdControl() to set. 





See also 
CdControl() 
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CdiILOC 
Time-code based CD-ROM disc position. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 
Structure 
typedef struct { 
u_char minute; Minute 
u_char second; Second 
u_char sector; Sector 
u_char track; Track number 
} CdILOC; 
Explanation 








Defines a time-code position on a CD-ROM, based on the time needed to reach that position when playing 
the disc from the beginning at normal speed. 


The track member is not used at present. 


Use CdlSetloc command of CdControl() to set. 


See also 
CdControl() 
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StHEADER 
Sector header. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 
Structure 
typedef struct { 
u_short id; Reserved by system 
u_short type; Data type (always 0x0160) 
u_short secCount; Sector offset within 1 frame 
u_short nSectors; Number of sectors comprising one frame 
u_long frameCount; Movie absolute frame number 
u_long frameSize; Movie data size (in long words) 
u_short width; Movie horizontal size 
u_short height; Movie vertical size 
u_long dummy7; Reserved by system 
u_long dummy2; Reserved by system 
CdlLOC /oc; File location 
} StHEADER; 
Explanation 


Movie sector header. If a header obtained with StGetNext() is written to this structure, the data can be 
accessed through the structure members. 


For details of the structure, refer to “STR: Streaming (Movie) Data” in the File Formats document. 
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CdComstr 

Get character string corresponding to command code (for debugging). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

char *CdComstr( 

u_char com) Command completion code 

Explanation 


For debugging. Get corresponding character string from processing status code. Example: CdINop returns 
“CdINop”, CdlSetloc returns “CdlSetloc”, and so on. 


Return value 
Pointer to start of character string. 


See also 
Cdlntstr(), CdSetDebug() 
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CdControl 

Issue primitive command to CD-ROM system. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdControl( 

u_char com, Command code 

u_char “param, Pointer to command arguments 

u_char *result) Pointer to return value storage buffer (requires 8 bytes) 

Explanation 


Issues the primitive command com to the CD-ROM system. param points to the arguments of the 
command, if any; set param to O for commands that do not require arguments. result points to a buffer 
used to hold the return value; if result is O, the return value is not stored. 


The values of command (com), arguments (param), and return value (result) are listed below. For the 
functions that are non-blocking, the actual transmission completion must be detected by CdSync() 


Table 10-1: Primitive commands 








Symbol Code Type of Operation Contents 

CdINop 0x01 Blocking NOP (No Operation) 

CdlSetloc 0x02 Blocking Set the seek target 
position 

CdlPlay 0x03 Blocking Commence CD-DA 
play 

CdlForward 0x04 Blocking Forward 

CdlBackward 0x05 Blocking Rewind 

CdlReadN Ox06 Blocking Start data read 
(with retry) 

CdlStandby 0x07 Nonblocking Stand by with disk 
rotating 

CdlStop 0x08 Nonblocking Disk stopped 

CdlPause Ox09 Nonblocking Pause at current 
position 

CdlMute OxOb Blocking CD-DA mute 

CdlDemute OxOc Blocking Cancel mute 

CdlSetfilter OxOd Blocking Choose ADPCM 
play sector 

CdlSetmode OxO0e Blocking Set basic mode 
(see Table 10-4) 

CdlGetoaram OxOf Blocking Gets current CD 
subsystem mode 

CdlGetlocL 0x10 Blocking Get logical location 
(data sector) 

CdlGetlocP 0x11 Blocking Get physical 
location (audio 
sector) 

CdlSeekL 0x15 Nonblocking Logical seek (data 
sector seek) 

CdlSeekP 0x16 Nonblocking Physical seek 
(audio sector seek) 

CdlReadS Ox1b Blocking Commence data 





read (no retry) 
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Table 10-2: Primitive commands that take arguments and their arguments 








Symbol Argument Type Contents 

CdlSetloc CdlLOC Start sector location 
CdlReadN CdlLOC Start sector location 
CdlReadS CdlLOC Start sector location 
CdlPlay CdlLOC Start sector location 
CdlSettilter CdIFILTER Set ADPCM sector play 
CdlSetmode u_char Set basic mode 





Table 10-3: Return values of primitive commands 





Return Value and Stored Byte Position 





Symbol O 1 2 3 4 5 6 7 
CdliGetparam Status Mode 

CdlGetlocL Min Sec Sector Mode File Chan 

CdlGetlocP Track Index Min Sec Frame Amin Asec Aframe 
CdlSeekL Status Btrack Etrack 

CdlSeekP Status Min Sec 





Note: all other commands return Status in the first byte. 


Return value 
1 if the command is issued successfully; O if failed. 


See also 
CdControlB(), CdControlF() 
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CdControlB 

Issue primitive command to CD-ROM system (Blocking-type function). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdControlB( 

u_char com, Command code 

u_char *param, Pointer to command arguments 

u_char *result) Pointer to return value storage buffer (requires 8 bytes) 

Explanation 


Issues the primitive command com to the CD-ROM system. param points to the arguments of the 
command, if any; set param to O for commands that do not require arguments. result points to a buffer 
used to hold the return value; if result is O, the return value is not stored. 


CdControlB() is identical to CdControl() except that it is blocking; that is, it waits for all commands to 
terminate before returning. For details, see CdControl(). 


Return value 
1 if issued successfully; O if failed. 


See also 
CdControl(), CdControlF() 
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CdControlF 

Issue primitive command to CD-ROM system (high speed). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdControlF( 

u_char com, Command code (see separate item) 

u_char *param) Pointer to an argument for command 

Explanation 


Issues the primitive command com to the CD-ROM system. param points to the arguments of the 
command, if any; set param to O for commands that do not require arguments. result points to a buffer 
used to hold the return value; if result is O, the return value is not stored. 





CdControlF() is fast because it does no handshaking with the subsystem (it does not even wait for 
command acknowledgement (ACk)). For details, see the commands and arguments of CdControl(), and 
the Run-time Library Overview. 


Return value 
Always returns 1. 


See also 
CdControl(), CdControlB() 
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CdDataCallback 

Define a routine to be executed when data transfer is completed. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.0 12/14/98 

Syntax 

void *CdDataCallback ( 

void (*func) () Pointer to address of callback function 

Explanation 


Defines a routine func to be executed when the data transfer initiated by CdGetSector() or CdGetSector2() 
has been completed. If func is O, then any previous callback routine is disabled. 





While func is executing, subsequent data transfer complete interrupts are masked. Therefore, func should 
return as soon as the necessary processing is completed. 


Return Value 
Address of previously set callback 


See also 
CdGetSector(), CdGetSector2(), CdDataSync() 
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CdDataSync 

Wait for or check a data transfer initiated by CdGetSector2(). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.2 12/14/98 

Syntax 

int CdDataSync( 

int mode) Polling mode 

Explanation 


If mode is O, the function waits for a data transfer initiated by CdGetSector2() to be completed. If mode is 1, 
the function polls the current status and returns. 


Return Value 
O if transfer is completed; 1 if transfer is still being performed; -1 if an error occurred. 


See also 
CdGetSector2(), CdDataCallback() 
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CdDiskReady 

Determine CD-ROM status after disc change. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 

Syntax 

int CdDiskReady( 

int mode) O: Blocking type, 1: Non-blocking type 

Explanation 


Checks the CD-ROM status after a disc change to determine whether a command can be issued safely. 
(Immediately after a disc is changed, there is a delay of a few seconds during which commands may not be 
issued.) 





When mode is 0, this function waits until the CD-ROM status has stabilized and commands may be issued 
before returning. When the mode parameter is 1, this function simply returns the current status. 


It is recommended that your program use this function immediately after initiating a disc change to wait for 
the disc cover to be closed and the CD-ROM status to stabilize. After this is done, check the disc format 
using the CDGetDiskType() and proceed accordingly. 


The maximum wait time required for returning from a blocking type function call is: 


DebuggingStation: 

CD-R Maximum of 12 seconds 
CD-DA Maximum of 12 seconds 
No disc Approximately 5 seconds 
PlayStation®: 

Black CD Maximum of 3 seconds 
CD-DA Maximum of 5 seconds 
No disc Approximately 5 seconds 


Although non-blocking type function returns immediately after checking the disc status, it cannot 
differentiate two error cases, the non-stable status and no disc case. Thus it is recommended to manage 
the time out according to the wait time shown above. 


Note: This function does not operate correctly on the DTL-H2000 development system. 





Return value 


CdlComplete The state where a command can be issued 
CdlDiskError Blocking type: No discs or defected disc 

Non-blocking type: Not stable, no discs, or defected disc 
CdlStatShellOpen Disc cover is open 
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CdFlush 
CD-ROM command flush. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.2 12/14/98 


Syntax 
void CdFlush(voic) 


Explanation 
Cancels the CD-ROM subsystem command being issued. The command being issued is invalidated and 
the subsystem can immediately accept commands. 





Since the data receipt mode is reset to CdIDataReady, be careful not to use this function when reading 
from the CD-ROM. 
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Get disc format. 


Library 
libcd.lib 


Syntax 


int CdGetDiskType(voic) 


Explanation 
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Introduced Documentation Date 
3.5 2/24/99 


Obtains the disc format. Currently only CD-ROM format can be recognized. 


On DebuggingStation, although PlayStation disc (black disc), CD-R, and other CD-ROM (ISO9600 format) 
can be recognized as a CD-ROM, on PlayStation (consumer model), only the PlayStation disc can be 
recognized as CD-ROM. CD-DA is always recognized as "Other Format". 


Note: Immediately after changing discs, it is recommended that your program call CdDiskReady(), 


followed by CdGetDiskType(). 


Since this function internally issues the CdliSetmode command and sets the mode to CdlModeSpeed, the 








mode must be reset as necessary after calling the function. 





For details, refer to the cdGetDiskType() function in sample\cd\tuto\tuto1 1.c. 





Note: This function does not operate correctly on the DTL-H2000 development system. 


Return value 
CdlCdromFormat 
CdlOtherFormat 
CdlStatShellOpen 
CdlStatNoDisk 


CD-ROM format 
Other format 

Disc cover is open 
No discs 
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CdGetSector 

Transfer sector buffer data to main memory. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdGetSector( 

void *madr, Main memory address to which the data is transferred 

int size) Size of data to be transferred (long words) 

Explanation 


Transfers data in the sector buffer to main memory. Transferring is processed in background. 
Sector size differs from mode to mode. See Table 10-4 for a list of modes. 


Although the data transfer can be divided several times to different memory addresses, the sector data 
must be read after the buffer becomes ready and before the buffer is overwritten by the next sector data. 
This function blocks until data transfer is complete. 








If less than a full sector is transferred during the callback, it is no longer necessary to issue dummy reads to 
update the pointer to the next sector. (In previous versions of CdGetSector() it was necessary to read 
excess data into a dummy area of RAM.) 





Return Value 
Always returns 1. 


See also 
CdDataSync(), CdDataCallback(), CdGetSector2() 
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CdGetSector2 

Transfer sector buffer data to main memory (Non-blocking type). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 4.0 12/14/98 

Syntax 

int CdGetSector2( 

void *“madr, Main memory address to which data is transferred 

int size) Size of data to be transferred (long words) 

Explanation 


Transfers sector buffer data to main memory. Since the transfer is carried out in cycle steal mode (a DMA 
mode that allows more sharing of the bus with other devices), an interrupt can be inserted within the 
transfer. Because this function is non-blocking, transfer completion must be monitored by CdDataSync() or 
CdDataCallback(). 


Furthermore, although an interrupt can be inserted during transfer in cycle steal mode, since a normal 
program cannot use a data bus, if there is a command to access the memory through a bus, processing is 
blocked at that point. 








Data transfer in cycle steal mode takes longer than in block mode (the mode used by CdGetSector‘(). 


If less than a full sector is transferred during the callback, it is no longer necessary to issue dummy reads to 
update the pointer to the next sector. (In previous versions of CdGetSector2() it was necessary to read 
excess data into a dummy area of RAM.) 





Return value 
Always returns 1. 


See also 
CdDataCallback(), CdDataSync(), CdGetSector(). 
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CdGetToc 

Read CD-ROM table of contents information. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdGetToc( 

CdlLOC “loc) Pointer to location table 

Explanation 


Get starting position of each track on the CD-ROM disc. 


The maximum number of tracks is 100. 


Return value 
Positive integer is a track number; anything else is an error. 


See also 
CdSearchFile() 
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Cdinit 
Initialize CD-ROM system. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 
void Cdlnit( 
Cdlnit mode) Reset mode (use 0) 


Explanation 


Resets the CD-ROM subsystem. The mode parameter is not used by current versions of the library and 
should be set to O. 





When initialization fails, up to four retries are performed. Since Cdlnit() and CdReset() reset the SPU sound 
volume and CD input volume to the SPU, etc., they must be called before libspu/libsnd initialization and 
setting functions. 





Return value 
1 if initialization is successful; O on failure. 


See also 
CdReset() 
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Cdintstr 

Get character string corresponding to command status code (for debugging). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

char *Cdintstr( 

u_char intr) Processing status code 

Explanation 


For debugging. Get character string corresponding to processing status code intr. For debugging. 


For example, CdlNolntr returns "CdlNolIntr", and so on. 


Return value 
Pointer to start of character string 


See also 
CdComstr(), CdSetDebug() 
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CdlintToPos 

Translate an absolute sector number to a minute/seconds/sector time code. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

CdlLOC *CdlIntToPos( 

int i, Absolute sector number 

CdlILOC “p) Pointer to a CdILOC structure that will be set to the position time code 

Explanation 


Calculate value for minute/second/sector from absolute sector number. 


Return value 
p 


See also 
CdPosTolnt() 
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CdLastCom 
Get last command issued by CDControl()//CDControlB() 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.2 12/14/98 


Syntax 
int CdLastCom(voic) 


Explanation 
Returns the last command issued by CDControl()/CDControlB(). 


See Table 10-1 under CDControl() for a list of the commands. 


Return Value 
Last command. 


See also 
CdControl(), CdControlB() 
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Get CD-ROM location most recently specified. 


Library Header File Introduced 
libcd.lib libcd.h 3.5 
Syntax 
CdILOC *CdLastPos(voia) 
Explanation 


Returns the latest location specified by one of the sub commands 
CdlSetloc/CdlPlay/CdlSeekL/CdlSeekP/CdlRead/CdlReads. 


Return value 
Pointer to the CdILOC structure containing the CD-ROM location. 
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Documentation Date 
12/14/98 
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CdMix 

Set attenuation for CD audio. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdMix( 

CdlATV *vol) Pointer to attenuator volume 

Explanation 


Set audio volume value for CD audio (CD-DA, ADPCM). 


Return value 
ik 
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CdMode 
Get latest CD-ROM mode. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 


Syntax 
int CdMode(voic) 


Explanation 
Returns the latest CD-ROM mode set. 


High speed since this function only refers to the status in the main memory. The mode buffer is updated 
when a CdlSetmode command is issued and also when the mode is specified in the arguments as in 
CdRead\(), etc. 


Table 10-4: CD Mode Settings 


Symbol Code Details 
CdlModeStream 0x100 Normal streaming 
CdiModeStream2 0x120 SUB HEADER 








information 

includes 
CdIModeSpeed 0x80 Transfer speed 0: Normal speed 1: Double speed 
CdIModeRT 0x40 ADPCM play 0: ADPCM OFF 1: ADPCM ON 
CdIModeSize1 0x20 Sector size 0: 2048 byte 1: 2340byte 
CdiModeSizeO 0x10 Sector size 0: — 1: 2328byte 
CdIModeSF 0x08 Subheader filter O: Off 1: On 
CdiModeRept 0x04 Report mode O: Off 1: On 
CdiModeAP 0x02 Autopause O: Off 1: On 
CdilModeDA 0x01 CD-DA play 0: CD-DA off 1: CD-DA on 








Return value 
CD-ROM mode. 


See also 
CdRead)() 
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CdPlay 
Play CD-DA tracks. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 


Syntax 
int CdPlay( 
int mode, 0: Stops playing 
1: Plays tracks in tracks array in the specified order. Stop at end. 
2: Plays tracks in tracks array in the specified order. Repeat at end. 
3: Returns an index of the array corresponding to the track currently being 





played. 
int *tracks, Pointer to array specifying the tracks to be played. Must end with O. 
int offset) Index of the tracks to be played. 


Explanation 


Plays multiple tracks specified by the array tracks in order. After playing the last track of the array, it repeats 
or stops playing according to the mode specified. 


All playing is done in units of tracks. Playing or stopping in the middle of a track is not allowed. 


Return value 
Index of the track currently being played (not the track number). -1 when it has already stopped playing. 
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CdPosTolint 

Translate time code to an absolute sector number. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdPosTolnt( 

CdlILOC “p) Pointer to a CdILOC structure containing the position time code 

Explanation 


Translates a minutes/seconds/sectors time code contained in a cdILOC structure pointed to by the p 
parameter into an absolute sector value. 


Return value 
Absolute sector number 


See also 
CdlntToPos() 
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CdRead 

Read multiple sectors from the CD-ROM. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdRead( 

int sectors, Read sector count 

u_long “buf, Pointer to read buffer 

int mode) CD-ROM subsystem mode, as defined for CdlSetmode command of 

CdControl() 
Explanation 


Reads one or more sectors of data from the CD-ROM to the specified buffer in memory. The starting 
position for the read is the position last specified for CdlSetloc. Each CdRead() requires a separate 
CdlSetloc command. 


CdRead\() is non-blocking. Check for completion using CdReadSync() or CdReadCallback(). CdRead() uses 
CdReadyCallback() internally, so that function cannot be used with CdRead)(). 








The return code from CdRead)() only indicates if the command was issued successfully or not. For 
information about CD-ROM errors which occur during reading, check the result array of CdReadSync(). 


Return value 
1 if command issued successfully, otherwise 0. 


See also 
CdControl(), CdRead2(), CdReadSync(), CdReadCallback() 
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CdRead2 

Start reading data from the CD-ROM. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdRead2( 

int mode) CD-ROM subsystem mode, as defined for CdlSetmode command of 

CdControl() 
Explanation 


Seeks to the position specified by CdlSetloc and starts reading data into the internal sector buffer. Starts 
streaming when the CdiModeStream flag is set in mode (see Table 10-4 for a list of modes). Starts ADPCM 
audio play when the CdiModeRT flag is set in the mode parameter. CdlModeSpeed can be used for multi- 
speed play. 


This function must be used in conjunction with CdGetSector() to transfer data from the internal sector buffer 
to the program’s desired destination buffer. CdGetSector() should be called to transfer data as soon as 
either CdReady() or CdReadyCallback() return the CdilDataReady flag. 


Return value 
1 if command issued successfully, otherwise 0. 


See also 
CdControl(), CdRead(), CdGetSector(), CdReady(), CdReadyCallback() 
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CdReadBreak 
Interrupt CdRead(). 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 4.0 12/14/98 


Syntax 
void CdReadBreak(voic) 


Explanation 
Used to interrupt CdRead(). Data which was read up until the interrupt is not secured. 


Executing CdReadBreak() immediately after executing CdRead() (when 1 sector has not been read), can 
cause an error. 


See also 
CdRead)() 
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CdReadCallback 

Define a callback function to be executed on completion of CdRead\(). 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

u_long CdReadCallback(void(*func)) Pointer to callback function address 

void (*func)(int status, Return code of the CdReadSync() 

u_char *result)) Pointer to an 8-byte array containing status and result 

information 
Explanation 


func defines the function to be called when CdRead() completes. If func is O, callback does not occur. func 
is passed two arguments: 





e status is either CdlComplete or CdlDiskError, corresponding to the return code of CdReadSync(). 
e result is a pointer to an 8-byte array containing status and result information, corresponding to the 
result argument of CdReadSync(). 


While func is executing, subsequent data transfer complete interrupts are masked. Therefore, func should 
return as soon as the necessary processing is completed. 


Return value 
Address of previously set callback. Can be used to restore the previous callback when processing ends. 


See also 
CdRead(), CdReadSync() 
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CdReadExec 

Load PlayStation-format executable program file from CD-ROM. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 

Syntax 

struct EXEC *CdReadExec( 

char “file) Pointer to executable file name 

Explanation 





Loads the executable program specified by file into main memory at the address specified by the program 
file header. It is a blocking function. 


After loading, the program can be executed as a child process using Exec(). The load address of the 
executable file should not overlap with the region of its parent process. 


Return value 
Pointer to an EXEC structure that describes the loaded program. 
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CdReadFile 

Read a CD-ROM file. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 

Syntax 

int CdReadFile( 

char “file, Pointer to file name 

u_long “addr, Pointer to main memory address to be read-in 

int nbyte) Data size to be read-in 

Explanation 


Reads nbyte of the file on CD-ROM. nbyte must be a multiple of 2048; reads the entire file if nbyte is O. file 
must contain a full path specification. All lowercase letters are converted to uppercase. When file is NULL, 
it starts reading from the next byte after the byte read by the last CdReadFile(). 








Although reading is performed in the background, because CdSearchFile() is called internally before reading 
begins, it is blocked for that period. Use CdReadSync() to determine when reading is completed. 


Return value 
Number of bytes read, if successful. On error, returns O. 


See also 
CdSearchFile), CdReadSync() 
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CdReadSync 

Check completion of CdRead() and related functions. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdReadSync( 

int mode, Await read completion 

u_char *result) Pointer to status storage buffer of command most recently completed 

Explanation 


Checks the current status of a data read operation initiated by CdRead(), CdReadFile(), and related 
functions. If mode is O, the function waits for the operation to complete. If mode is 1, it returns the current 
status immediately. 


Return value 
Number of sectors remaining. If operation completed, O is returned. On error, -1 is returned. 


See also 
CdRead(), CdReadSync() 
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CdReady 

Wait for CD-ROM data to be ready. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdReady( 

int mode, Wait until data is prepared 

u_char *result) Pointer to status storage buffer of command most recently completed. 

Explanation 


Used after a CD-ROM read is initiated using CdRead2(), CdControl (CdlReadS), or CdControl (CdlReadN) 
to determine if there is data available in the sector buffer which is ready to be transferred using 
CdGetSector(). 


If mode is O, the function waits for the operation to complete. If mode is 1, it returns the current status 
immediately. 


Return value 
Status can be one of the following: 


CdlDataReady There is data available for transfer 
CdlDiskError Error detected 

CdlNoIntr No preparation-completed data 
See also 


CdReadyCallback(), CdRead2(), CdControl(), CdGetSector() 
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CdReadyCallback 

Define CdReady callback function. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

u_long CdReadyCallback(void(*func)) Pointer to callback function address 

void (“func)(int status, Processing status of read command 

u_char *result)) Pointer to an 8-byte array containing status and result 

information 
Explanation 


Defines a callback routine func to be executed when data is available in the sector buffer following a CD- 
ROM read initiated using CdRead2(), CdControl (CdlReadS) or CdControl (CdlReadN). If func is NULL, any 
previous callback routine is disabled. 


func is passed two arguments: 


e status is either CdliComplete or CdlDiskError, corresponding to the return code of CdSync() (although 
CdSync() is not called). 

e result is a pointer to an 8-byte array containing status and result information, corresponding to the 
result argument of CdSynci(). 





While func is executing, subsequent data available interrupts are masked. Therefore func should return as 
soon as the necessary processing is completed. 


Return value 
Address of previously set callback. Can be used to restored the previous callback. 





See also 
CdReady(), CdRead2(), CdControl(), CdSync() 
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CdReset 

Initialize CD-ROM subsystem. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdReset( 

int mode) Reset mode 

Explanation 


Initializes the CD-ROM subsystem. Lower-level alternative to Cadlnit(). 
Unlike Cdlnit(), this function does not initialize the event environment related to CD-ROM. 
mode can be: 


e 0: Initialization of CD subsystem only (volume settings specified in previous sound libraries are saved) 
e = 1: Initialization of CD subsystem and CD audio volume (CD-DA, ADPCM) 


No retry is carried out. Since Cdlnit() and CdReset() reset the SPU sound volume and CD input volume to 
the SPU, etc., they must be called before libspu/libsnd initialization and setting functions. 


Return value 
1 if initialization successful; O if unsuccessful. 


See also 
Cdlnit() 
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CdSearchFile 

Get location and size from CD-ROM file name. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

CdlFILE *CdSearchFile( 

CdlFILE “fp, Pointer to CD-ROM file structure pointer 

char *name) Pointer to a file name 

Explanation 





Determines the position time code (minutes, seconds, sectors) and total length of the specified file on the 
CD-ROM. The result is stored in the CdlFILE structure pointed to by fp. 


name must be a complete path to the file. 





CdSearchFile() caches directory information, so subsequent consecutive calls for files in the same directory 
do not require additional CD-ROM reads. Only one directory is cached at a time, and reading information 
for a file in another directory invalidates the entire cache. 








For the best possible performance, include file location and size information in your program at compile 
time instead of using CdSearchFile(). 


Return value 
Pointer to the CD-ROM file structure obtained; O if file not found. 
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CdSetDebug 


Set debug level. 


Library 
libcd.lib 


Syntax 


int CdSetDebug( 
int /eve/ 


Explanation 


Introduced 
2.X 


Set debug level for CD-ROM subsystem. The possible values of /evel are: 


O: 
i: 
2: 


3: 


Return value 
Previously set debug mode 


No checks performed 

Check primitive commands 

Print execution status of primitive 
commands 

Print issued command error 
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Documentation Date 
2/24/99 
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CdStatus 
Get latest CD-ROM status. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.0 12/14/98 


Syntax 
int CdStatus(void) 


Explanation 

Obtains the latest reported CD-ROM status. 

This function operates at high speed because it simply returns the status code maintained by the CD-ROM 
system. The status buffer is updated whenever a CD-ROM command is issued. To explicitly obtain the 


absolute most current status, issue a CdControl(CdINop) command immediately before your CdStatus() 
call. 


Return value 
CD-ROM Status. 
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CdSync 

Wait for or check completion of CD-ROM command. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

int CdSync( 

int mode, Waits for command termination 

u_char *result) Pointer to status storage buffer of command most recently completed. 

Explanation 


If mode is O, waits for command termination and returns. If mode is 1, determines current status and 
promptly returns. 


Return value 
Command execution status is indicated by the following values: 


CdlComplete: Command complete 
CdlDiskError: Error detected 

CdlNolntr: Command is being executed 
See also 


CdSyncCallback() 
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CdSyncCallback 

Define CdSync callback function. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

u_long CdSyncCallback(void(*func)) Pointer to callback function address 

void (*func)(int status, Return code of CdSync() 

u_char *result)) Pointer to an 8-byte array containing status and result 

information 
Explanation 


Defines a callback routine func to be executed when a CdControl() command is completed. If func is NULL, 
any previous callback routine is disabled. 


func is passed two arguments: 


e status is either CdlComplete or CdlDiskError, corresponding to the return code of CdSync(). 
e result is a pointer to an 8-byte array containing status and result information, corresponding to the 
result argument of CdSynci(). 


While func is executing, subsequent CD-ROM command complete interrupts are masked. Therefore, func 
should return as soon as the necessary processing is completed. 


Return value 
Address of previously set callback. Can be used to restore previous callback. 





See also 
CdSync() 
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StCdinterrupt 


Handler for interrupts from CD-ROM (internal function). 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 
void StCdinterrupt(voic) 


Explanation 

Used as the CdReadyCallback routine by StSetStream() and StSetEmulate(). It transfers sectors from the 
CD controller to the streaming ring buffer as they become available. This function does not need to be 
called directly by the user when playing movies in 16-bit mode. 





When playing a movie in 24-bit mode, there is a potential hardware conflict between the CD subsystem 
and the MDEC image decompression system which can result in corrupted data. To avoid this, 
StCdlnterrupt() may defer transferring a sector and instead set a flag variable called StCdlnterFlag to 
indicate that a CD sector is ready to be transferred. Once the MDEC is finished transferring data, your 
application should check StCdlIntrFlag and call StCdlInterrupt() directly if it is set. Please consult the Sony 
sample code for movie playback for examples of the proper workaround. 





See also 
CdGetSector(), DsGetSector() 
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StClearRing 
Flush ring buffer. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 
void StClearRing(voic) 
Explanation 


Flush ring buffer. Flushing the ring buffer when jumping tracks is effective in preventing excess frames from 
showing up. 
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StFreeRing 


Release ring buffer. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 
u_long StFreeRing( 
u_long “base) Pointer to starting address of user data area of released 1 frame 


Explanation 


The area obtained by StGetNext() is locked. StFreeRing() releases this locked region. The released region is 
the region for one frame's worth of data which is used as the base for the starting address of the user 
region. Linked sector header regions are also released. 








If a region locked by StGetNext() is not released when its use ends, the ring buffer will overflow and 
streaming will come to a halt. 


Return value 
O if release succeeded; 1 if release failed (for example, trying to release something that wasn’t locked). 
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StGetBackloc 

Return location and ID of first frame in the ring buffer in order to avoid any frame skip. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 

Syntax 

int StGetBackloc( 

CdlLOC */oc) Pointer to latest location of the first frame. 


(use DsILOC */oc when using libds) 


Explanation 
Returns the latest location information and ID of the first frame in the current ring buffer. 





The location information is used as the access target value in order to avoid frame skip due to ring buffer 
overflow. The frame skip due to ring buffer overflow can be avoided by re-accessing the frame location 
obtained by this function. This function is not appropriate for data with XA audio since it requires data 
access. 


Please refer to \psx\sample\cd\movie\tuto3.c for usage example. 
This function is valid only for CdliModeStream2 mode. 


Return value 
Frame ID that should be used on restart of streaming. -1 for error indicating non-StModeStream2 mode. 
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StGetNext 

Get one frame of ring buffer data. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

u_long StGetNext( 

u_long *adar, Pointer to starting address of user data region for 1 frame of retrieved 

data 
u_long *header) Pointer to starting address of sector header region for 1 frame of 





retrieved data 


Explanation 


Gets one frame of ring buffer data. If the next frame of data is ready in the ring buffer, the starting address 
of the user data and the sector header are stored in addr and header respectively. 








The region the data is taken from is locked until StFreeRing() is called, so it cannot be destroyed by new 
data. 


The data region has a contiguous address and the ring buffer does not loop in mid-frame. 


Return value 
O, if a frame of data is taken from the ring buffer. If it is not ready, 1 is returned. 


See also 
StGetNextS(), StFreeRing() 


Run-Time Library Reference 


10-50 CD/Streaming Library Functions 





StGetNextS 
Get one frame of ring buffer data from memory. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 
Syntax 
u_long StGetNext( 
u_long *adar, Pointer to user data region starting address for 1 frame of retrieved 
data 
u_long *header) Pointer to sector header region starting address for 1 frame of retrieved 
data 
Explanation 
Gets one frame of ring buffer data. The starting addresses and the sector header are stored in addr and 
header respectively. 


Return value 
O, when one frame of data is taken from the ring buffer. 


See also 
StGetNext() 
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StNextStatus 
Return status of the next frame. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 
Syntax 
u_long StNextStatus( 
u_long “addr, Pointer to starting address of the user data region for 1 frame of retrieved 
data 
u_long *header) Pointer to starting address of sector header region for 1 frame of retrieved 
data 
Explanation 


Obtains the status of the next frame of ring buffer data. The internal state is not affected by calling this 
function. 


Return value 
Status can be: 


StFREE Next frame is not in the ring buffer. 

StCOMPLETE Next frame is completely read into the ring 
buffer. 

StBUSY Next frame is being read into the ring 
buffer. 

StLOCK Next frame is being processed; i.e. one 


frame is obtained by calling StGetNext() 
but StFreeRing() has not been called. 
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StRingStatus 

Return status of ring buffer. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 3.5 12/14/98 

Syntax 

void StRingStatus( 

short *free_sectors, Pointer to the number of free sectors on the ring buffer. 

short *over_sectors) Pointer to the difference between the sector positions of CD-ROM data read 





in and the sector positions currently being processed. 


Explanation 
Reports the ring buffer status with two variables specified as arguments: 


e free_sectors is the number of sectors with no data in the unused area of the ring buffer. The larger 
free_sectors is, the more free space in the ring buffer. 

e over_sectors is the difference between the sector positions for CD-ROM data read in and the sector 
positions currently being processed. The larger over_sectors is, the more unprocessed data in the ring 
buffer. 








The sum of free_sectors and over_sectors and the total ring buffer size is nearly equal. The reason for not 
having an exact match in size is that when one frame cannot fit in completely close to the end, rewind 
occurs. 





Frame skip caused by insufficient free space in the ring buffer can be detected by calling this function. 
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StSetChannel 


Set streaming channel. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 

int StSetChannel( 

u_long ch) Playback channel 

Explanation 

Sets streaming playback channel to ch (0-31). The channel stores the STR data at the authoring level. 





Return value 
O if the channel is set; 1 otherwise. 
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StSetEmulate 
Set parameters for streaming emulation. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 2/24/99 
Syntax 
void StSetEmulate( 
u_long “addr, Pointer to emulation data starting address 
u_long /oc, Set color mode 
u_long start_frame, Streaming start frame 
u_long end_frame; Streaming end frame 
void (*func7)(), Address of function called back for each frame of data. If O, no callback 
occurs. 
void (“func2)()) Address of function called back when streaming ends. If 0, no callback 
occurs. 
Explanation 


Sets parameters for streaming emulation. Emulation means that CD-ROM data is put into memory in 
advance and data streaming is performed from memory, not from the CD-ROM, which provides only data- 
ready timing. In streaming emulation, play time is limited to a few seconds because of limits in memory 
capacity. Still, emulation is easier than using a CD-ROM emulator. 





STR-format data needs to be loaded to addr in advance. See StSetStream() for details on other arguments. 
(loc is the same as mode.) 


See also 
StSetStream() 
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StSetMask 

Control the playing of streaming. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 

Syntax 

void StSetMask( 

u_long mask, Streaming play on/off 

u_long start, StSetStream() start_frame 

u_long end) StSetStream() end_frame 

Explanation 


Turns streaming play ON/OFF. There is no mechanical timing lag compared to CD-ROM drive pause and 
playback, and instant ON/OFF is possible. 


mask is O for Play, and 1 for Pause. 


Resets start and end of StSetStream() trigger frame values. 


See also 
StSetStream() 
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StSetRing 
Set ring buffer. 


Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 

void StSetRing( 

u_long *ring_adar, Pointer to ring buffer starting address 

u_long ring_size) Ring buffer size (in sectors) 

Explanation 

Secures a ring buffer of a size specified by ring_size from an address specified by ring_addr. To use the 
Streaming Library, you must first call this function. 


Because only form-1 CD-ROM sectors are supported at present, one sector of data area is 2048 bytes. 





See also 
StUnSetRing() 
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StSetStream 
Set streaming parameters. 
Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 
Syntax 
void StSetStream( 
u_long mode, Set color mode 
u_long start_frame, Frame to start streaming 
u_long end_frame, Frame to end streaming 
void (*func7)(), Address of function called back for each frame of data. If O, no callback 
occurs. 
void (“func2)() Address of function called back when streaming ends. If 0, no callback 
occurs. 
Explanation 


Sets streaming parameters. Argument are as follows: 


e mode sets color mode. 0 = 16-bit mode; 1 = 24-bit mode. 

e  start_frame specifies the frame number (stored in STR data) that starts streaming. Streaming doesn’t 
begin until this frame is reached. If you want to play the data starting in the middle, you must specify an 
appropriate frame number. When you specify O, streaming commences no matter what the frame 
number is. 

e end_frame specifies the frame number (stored in STR data) that ends streaming. Streaming ends when 
this frame is reached. If you specify a number large enough, it plays the CD-ROM data to the end and 
terminates. When you specify O, all the data is stored in the ring buffer and the function automatically 
terminates. This takes a large ring buffer, and the function is successful when streaming is from 
memory. 

e func? is the address of the callback function called when one frame’s worth of data is generated. 

e func2 is the address of the callback function called when streaming is completed. 














To correctly exit from a streaming application, the end of streaming should not be set by end_frame. Set 
end_frame to Oxffffffff, and code an appropriate endpoint from within the loop. 
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StUnSetRing 


Release interrupt used by streaming library. 





Library Header File Introduced Documentation Date 
libcd.lib libcd.h 2.X 12/14/98 


Syntax 
void StUnSetRing(voia) 


Explanation 
Release two interrupt functions CdDataCallback() and CdReadyCallback() hooked by 
CDRead2(CdiModeStream) and return to initial state. 


If the streaming library is not used when streaming ends and control transfers to another program, the 
interrupt hooks which call this function need to be returned to the initial state. 





It is necessary to link libds when using this function. 


See also 
StSetRing(), StSetStream( 
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Structures 
DsIATV 
Audio attenuator. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 
Structure 
typedef struct { 
u_char vai0; CD (L) -> SPU (L) attenuation 
u_char valt; CD (L) -> SPU (R) attenuation 
u_char val2; CD (R) -> SPU (R) attenuation 
u_char va/3; CD (R) -> SPU (L) attenuation 
} DsIATV; 
Explanation 


Structure for setting the CD volume (CD-DA and CD-XA). 
The values for valO - val3 can range from O to 128. For standard stereo volume adjustments, 


val0 is set to the L channel volume 
val7 is set to O 
val2 is set to the R channel volume 
val3 is set to O 
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DsIFILE 
9660 file descriptor. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 
Structure 
typedef struct { 
DsILOC pos; File position 
u_long size; File size (in bytes) 
char name/76]; Filename 
} DsIFILE; 
Explanation 


Stores the position and size of a type 9660 CD-ROM. 
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DsIFILTER 
ADPCM channel. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 
Structure 
typedef struct { 
u_char file; File number 
u_char chan; Channel number 
u_short pad; Reserved for system use 
} DsIFILTER; 
Explanation 


Specifies the ADPCM sector channel to be played back. 
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DsILOC 
CD-ROM location. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 
Structure 
typedef struct { 
u_char minute; Minutes 
u_char second; Seconds 
u_char sector; Sectors 
u_char track; Track number (currently unused) 
} DsILOC; 
Explanation 





Specifies the CD-ROM position. Each element is specified using BCD 


See also 
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Functions 





DsClose 
Close the libds system. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 


Syntax 
void DsClose(voia) 


Explanation 
Closes the libds system, resets the libds kernel state machine, and detaches the callback function which 
controls the libds kernel that has been forked in the system. 








This function must be called whenever control is passed to a child process, LoadExec() is performed, or 
when CD control functions outside of libds are used. Call Dslnit() to reopen libds. 


See also 
Dslnit() 
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DsCommand 
Add primitive command to the command queue. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 
Syntax 
int DsCommand( 
u_char com, Command code 
u_char “param, Pointer to argument for command (u_char[4]) 
DsICB cbsync, Pointer to callback function 
int count) Number of retries (0: no retries, -1: unlimited retries) 
Explanation 





Adds a command to the queue to be performed in the background. If execution of the command fails, it is 
retried count times. An error is returned if the command failed to complete after it was retried. 





Separate callback functions can be set for each command. The callback triggers when the command 
completes (or returns an error). The execution status of a command can be obtained with DsSync\(). 


Return value 
The command ID (>0) if the command issued successfully, otherwise O. 


See also 
DsSync() 
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DsComstr 

Get the character string corresponding to each command code (for debugging) 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.3 12/14/98 

Syntax 

char *DsComsitr( Command completion code 

u_char com) 

Explanation 


Gets the corresponding character string from the process status code (used for debugging). For example, 
DsINop returns “DsINop’”, DslSetloc returns “DslSetLoc”, and so forth. 


Return value 
Pointer to start of character string. 


See also 
Dslnit() 
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DsControl 

CdControl() compatibility function. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsControl( 

u_char com, Command code 

u_char *param, Pointer to arguments for command (u_char[4]) 

u_char *result) Pointer to storage for the return value (u_char[8}) 

Explanation 


Provides the same interface as CdControl(). Unlike CdControl(), however, the command is handled such 
that the function blocks until the end of the operation, even if the command itself is non-blocking. 








Return value 
1: Execution of command was successful. 0: Execution of command failed. 


See also 
CdControl() (see libcd), DsControlB(), DsControlF() 
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DsControlB 

CdControlB() compatibility function. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

int DsControlB( 

u_char com, Command code 

u_char “param, Arguments for command (u_char|4]) 

u_char *result) Return value for command (u_char[8]) 

Explanation 


Provides the same interface as CdControlB(). The actual timing differs somewhat since the command 
queue is used. 





Return value 
1: Execution of command was successful. 0: Execution of command failed 


See also 
CdControlB() (see libcd), DsControl(), DsControlF() 
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DsControlF 

CdControlF() compatibility function. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

int DsControlF( 

u_char com, Command code 

u_char *“param) Pointer to arguments for command (u_char]4]) 

Explanation 


Provides the same interface as CdControlF() except for a few differences such as timing. 








Internally, the specified command is simply added to the command queue. Note that the command ID is 
provided in the return value. 


CdControlF() waits for the previous command to complete execution before issuing the new command. 
DsControlF(), on the other hand, adds the new command to the queue if the previous command has not 
completed execution. 


Return value 
The command ID (>0) if the command was successfully added to the queue; O otherwise. 


See also 
CdControlF() (see libcd), DsControl(), DsControlB() 
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DsDataCallback 

Set exit calloack for DsGetSector() and DsGetSector2(). 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

void (*DsDataCallback( 

void(*func)() )) Pointer to callback function 

Explanation 


Defines func as the callback to be executed on completion of a read operation initiated by DsGetSector() or 
DsGetSector2(). No callback is generated when func is set to 0. 


This callback is really only useful with DsSector2(), since the transfer of data is finished when DsGetSector() 
exits. 


Return value 
Pointer to previous callback. 


See also 
DsGetSector(), DsGetSector2(), DsDataSync() 
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DsDataSync 

Wait for completion of DsGetSector2. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsDataSync( 

int mode) O: Wait for end of transfer 


1: Check current status and return immediately 


Explanation 
Waits for the transfer performed by DsGetSector2() to complete. 


Return value 
1: transfer is in progress. O: transfer is complete 


See also 
DsGetSector(), DsGetSector2(), DsDataCallback() 
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DsEndReadySystem 

End simple callback system. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 


void DsEndReadySystem(voic) 


Explanation 
Ends simple callback system. 


This function is executed within the callback function provided to DsStartReadySystem(). 


See also 
DsStartReadySystem() 
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DsFlush 

Flush the command queue. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 


void DsFlush(voia) 


Explanation 


All commands that have been entered in the command queue are flushed. Currently executing commands 
are allowed to complete, but the results are not saved and callbacks are not invoked. 








If acommand is executing when this function is called, it is allowed to complete. Subsequent commands 
are put into a new queue. 
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DsGetDiskType 

Get CD type. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 2/24/99 

Syntax 


int DsGetDiskType(voic) 
Explanation 
Gets the type of CD currently installed: either a PlayStation (black) or non-PlayStation disk. 


This function blocks until the system status (the status obtained from DsSystemStatus()) changes to 
DslReady. 


The debugging station recognizes ISO9660 CDs (including CD-Rs) as tyoe DsICdromFormat. 
This function does not operate properly on the DTL-H2000. 


This function internally changes the operation mode. Since the operation mode is DsIModeSize1 (0x20) 
when the function is complete, the mode must be reset as necessary. 





Return value 


DslCdromFormat PlayStation® disk 
DslOtherFormat Any other type of CD 
DslStatNoDisk CD is not installed 
DslStatShellOpen CD cover is open 
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DsGetSector 

Transfer data from the sector buffer to main memory. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsGetSector( 

void *madr, Pointer to destination area in main memory 

int size) Transfer size (long word) 

Explanation 


Data is transferred from the sector buffer to the storage area in main memory pointed to by maar. 
This function blocks until the end of the transfer operation. 
The sector size varies according to the mode. 


The data from the sector buffer can be transferred to memory over a number of iterations. The sector data 
in the buffer must be transferred to memory before it is overwritten by data from the next sector. 





The transfer is complete when the function returns. 


Return value 
Always returns 1. 


See also 
DsDataCallback(), DsDataSync(), DsGetSector2() 
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DsGetSector2 

Transfer data from the sector buffer to main memory (non-blocking). 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsGetSector2( 

void *maar, Pointer to destination area in main memory 

int size) Transfer size (long word) 

Explanation 


Data is transferred from the sector buffer to the storage area in main memory pointed to by maar. 





The transfer is performed in cycle-stealing mode so interrupts may be received during the transfer. 


Since DsGetSector2() is a non-blocking function that can return after the transfer starts, the completion of 
transfer must be determined using DsDataSync() or DsDataCallback(). 


Receiving interrupts and accessing memory from the CPU are possible even during transfers in cycle- 
stealing mode. However, other DMA’s are blocked until the transfer is completed. 





Data transfers in cycle-stealing mode are more time-consuming compared to those in blocking mode (the 
mode used by DsGetSector‘()). 


Return value 
Always returns 1. 


See also 
DsDataCallback(), DsDataSync(), DsGetSector() 
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DsGetToc 
TOC read. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.1 12/14/98 


Syntax 


int DsGetToc( 
DsILOC *loc) Location table 


Explanation 
The starting position of each track on the CD-ROM is obtained. 


The largest track number is 100. 


Return value 
Positive integer: track number; Other values: error 
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DslInit 

Perform system initialization. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 


int DsInit(voic/) 
Explanation 
Initializes the libds system. 


Dslnit() needs to be called just once at the beginning of a program or when restarting a system that was 
stopped with DsClose(). 


Calling Dslnit() in the middle of a program may cause improper operation. DsReset() should be used if 
initialization needs to be performed in the middle of a program. 


Because Dslnit() resets the SPU sound volume and the CD input volume to SPU, etc., it should either be 
called before libspu and libsnd initialization/setting functions or they should be reset after Dslnit() is called. 


Return value 
1 if successful; O if the operation failed. 


See also 
DsClose(), DsReset() 
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Dslinstr 

Get the corresponding character string for the command process status (for debugging). 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.3 12/14/98 

Syntax 

char * DsIntStr( Execution status code 

u_char intr) 

Explanation 


For debugging. Gets the corresponding character string from the process status code. 








Table 11-1 
Process status Character string 
DslNolntr ”Nolntr” 
DslComplete “Complete” 
DslDiskError “Disk Error” 





Return value 
Pointer to start of character string. 


See also 
DsComstr(), DsSetDebug() 


Run-Time Library Reference 


11-24 Extended CD-ROM Library Functions 


DsIntToPos 

Get minutes, seconds, sectors from absolute sector number. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

DsILOC *DsIntToPos( 

int i, Absolute sector number 

DsILOC *p) Pointer to buffer for storing result 

Explanation 


The absolute sector number specified by / is converted to minutes, seconds, and sectors and the result is 
stored in the DsILOC structure pointed to by p. 


Return value 
Pointer to result buffer 


See also 
DsPosTolnt() 
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DsLastCom 

Get the command issued last. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.3 9/1/99 

Syntax 


u_char DsLastCom(voic) 


Explanation 
Returns the primitive command code issued last. 





However, because this function is replaced by DsINop in libds in the following situations, the desired value 
may not be returned. 

e When DslPause is issued and then reissued it after it is successful. 

e When DslStop is issued while the spindle is stopped. 

e When DslStandby is issued while the spindle is revolving. 





Return value 
Primitive command code 


See also 
DsControl() 
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DsLastPos 
Get the last setloc position. 


Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 


Syntax 


DsILOC *DsLastPos( 
DsILOC *p) Pointer to buffer in which position is stored 


Explanation 
The last setloc position is obtained and the result is stored in the DsILOC structure pointed to by p. 


Return value 
Pointer to result buffer 
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DsMix 


Set attenuator. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 


Syntax 


int DsMix( 
DslATV *vo/) Attenuator volume 


Explanation 
The CD audio volume (CD-DA/ADPCM) is set to the value in the DsIATV structure pointed to by vol. 


Return value 
1. 


Run-Time Library Reference 


11-28 Extended CD-ROM Library Functions 





DsPacket 

Add a sequence of commands to the queue. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

int DsPacket( 

u_char mode, Operating mode 

DsILOC *pos, Pointer to DsILOC structure specifying target position 

u_char com, Last command to be executed 

DsICB *cbsync, Callback function to be triggered when all the commands have been 

executed 
int count) Retry count (0: no retries, -1: unlimited retries) 
Explanation 


Adds a sequence of commands that perform a data read (playback) to the queue. 
The commands added to the queue are: DsIPause; DsISetmode mode; DslSetloc pos; com. 


The commands that can be specified for com are: DsIPlay, DsIReadN, DslReadS, DslSeekP, or DslSeekL. 
If com is DsIPlay, DsIReadN, or DslReadS, execution is performed up to and including the data read 
(playback). If com is DsISeekP or DslSeekL, the seek is performed and the system enters a pause state. 








If any command in the sequence generates an error, a retry is performed starting with the first command, 
up to a maximum of count times (or unlimited times if count=-1). An error is generated if the operation is 
not successful after count retries. 


DsSync() can be used to obtain the execution status. When all the commands in the sequence are 
successful or if an error is generated, the callback function cbsync is triggered. 





An error is generated if the queue does not have enough space for the command sequence. 


Return value 
The command ID (>0) if the command was added to the queue; 0 if the command failed. 





See also 
DsCommand(), DsQueueLen() 
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DsPlay 

Play back CD-DA tracks. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

int DsPlay( 

int mode, Mode 

int “tracks, Pointer to array specifying the tracks to be played back; the last element of 

the array must be 0O. 
int offset) Index for track to begin playback 
Explanation 


The tracks specified by the tracks array are played in sequence in the background. 


When the final track in the series is done, playback is repeated or is stopped, depending on mode. The 
values available for mode are shown below. 











Table 11-2 
Mode Description 
O Stop playback 
1 Play back the tracks in sequence; then stop playback. 
2 Play back the tracks in sequence; then repeat from beginning. 
3 Return the index of the track currently being played 





Playback is performed in increments of tracks. Playback cannot start or stop in the middle of a track. 


Return value 
The track currently being played (the index in the tracks array rather than the absolute track number). 


-1 means that all tracks have finished playing. 
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DsPosTolint 

Get absolute sector number from minutes, seconds, sectors. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsPosTolnt( 

DsILOC *p) Pointer to DslLoc structure containing minutes, seconds, sectors 

Explanation 


Calculates the absolute sector number from the minutes, seconds, and sectors in the DsILOC structure 
pointed to by p. 


Return value 
The absolute sector number. 


See also 
DsIntToPos() 
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DsQueueLen 

Get the number of commands stored in the command queue. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 


int DsQueueLen(voia) 
Explanation 
Obtains the number of primitive commands stored in the command queue. 


The commands issued by DsPacket() are not removed from the queue until they all successfully complete. 
Therefore the number of commands returned by DsQueueLen() remains unchanged during execution of the 
packet. 





The currently executing command is considered to be in the queue. The maximum number of commands 
that the queue can hold is defined by the DsIMaxCOMMANDS macro constant. 


Return value 
Number of commands in queue. 


See also 
DsPacket() 
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DsRead 
Read data. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 
Syntax 
int DsRead( 
DsILOC “pos, Pointer to DsILOC structure specifying starting position of CD 
int sectors, Number of sectors to read 
u_long “buf, Pointer to buffer to store read data 
int mod) Operating mode to be used when data is being read 
Explanation 


Reads CD data starting at the location specified by the DsILOC structure pointed to by p. The data is 
stored in the buffer pointed to by buf. 


The operation is performed in sectors, so the size of buf must be a multiple of 1 sector=2048 bytes (512 
words). 


Reading is performed in the background after DsRead() has executed and exited. Successful execution of 
the function does not indicate that the data has been successfully read. 





Note: The arguments are different from CdRead(). With DsRead(), the starting position of the data must be 
specified. 


Return value 


Positive integer: the id of the packet that was issued within the function, if execution was successful. 
O: function execution failed. 





See also 
DsReadBreak(), DsReadCallback(), DsReadSync(), CdRead\() (see libcd) 
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DsRead2 


Begin playback of movie. 


Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 


Syntax 

int DsRead2( 

DsILOC “pos, Pointer to DsILOC structure specifying starting position of CD 

int mod) Operating mode during playback 

Explanation 

Plays back the movie starting at the location specified by the DsILOC structure pointed to by pos. 


A libds streaming library callback is set and the reading of data is begun with DslReadS. 


Note: The arguments are different from CdRead2(). With DsRead2(), the starting position of the data must 
be specified. 





Return value 
The command ID (>0) if the function succeeded; O if the command failed. 


See also 
DsCommand(), CdRead2\() (see libcd) 
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DsReadBreak 

Interrupt DsRead\() operation. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 


void DsReadBreak(voic) 


Explanation 
Interrupts a DsRead() operation. 


See also 
DsRead() 
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DsReadCallback 

Set a callback function to be called when DsRead)( is finished. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 

DsICB DsReadCallback( 

DsICB func) Pointer to callback function 

Explanation 


Defines func as the callback to be triggered when DsRead() completes. 


Return value 
Pointer to previous callback function 


See also 
DsRead() 
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DsReadExec 


Read an executable file. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 


Syntax 

struct EXEC *DsReadExec( 

char “file) Filename 
Explanation 


Loads the executable file specified by file from the CD-ROM and stores it in main memory. It is a blocking 
function. 





The loaded file is executed as a child process using Exec(). The load address of the executable file must 
not overlap with the area used by the parent process. 


Return value 
Pointer to EXEC structure of the loaded executable file. 


See also 
Exec() (See libapi) 
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DsReadFile 

Read a file from CD-ROM. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 

int DsReadFile( 

char “file, Filename 

u_long “addr, Pointer to buffer in memory for storing read data 

int nbyte) Number of bytes to read 

Explanation 


Reads nbyte bytes from the CD-ROM file specified by file and stores them at the buffer pointed to by adar. 





nbyte must be a multiple of 2048; if it is O, the entire file is read. If file is NULL, the read operation begins 
from the point where the previous DsReadFile() left off. 





The filenames must all be represented by absolute paths. Lowercase characters are automatically 
converted to uppercase. 





Although the read is performed in the background, DsSearchFile() is called internally before the read begins, 
so it is blocked for that period. Use DsReadSync() to check for completion of reading. 


Return value 
The number of bytes read, or O if an error occurred. 





See also 
DsRead(), DsReadSync(), DsSearchFile() 
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DsReadSync 

Wait for completion of DsRead(). 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 

int DsReadSync( 

u_char *result) Pointer to buffer holding execution results (u_char[8]) 

Explanation 





Waits for completion of DsRead(). Returns the execution status of DsRead() at the point when 
DsReadSync() was called. 


Return value 


Positive integer: the remaining number of sectors. 
0: DsRead() has completed. 
—1: an error was detected (DsRead() was interrupted). 


See also 
DsRead() 
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DsReady 


Check for arrival of data. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 


Syntax 


int DsReady( 
u_char *result) Pointer to buffer for storing results (u_char[8]) 


Explanation 


Determines the status of a data read operation (DsIReadS/DslReadN) and stores the result in the buffer 
pointed to by result. 


In report mode, DsReady() checks for arrival of the report from DA playback. 


The sector buffer value is meaningful only for data reads. 


Return value 


DslDataReady New data has arrived in the sector buffer. 

DslNolntr New data has not arrived. 

DslDataEnd Final sector has been confirmed (only for 
DA playback). 

See also 


DsReadyCallback() 
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DsReadyCallback 


Set up Ready callback function. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 

DsICB DsReadyCallback( 

DsICB func) Pointer to callback function 

Explanation 


Sets the Ready callback to the function pointed to by func. It is called for data ready interrupts, data end 
interrupts (generated only for DA playback), and all error interrupts. 


Return value 
Pointer to previous callback function. 


See also 
DsReady() 
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DsReadySystemMode 

Set action of cover open/close for the simple callback. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.1 12/14/98 

Syntax 

int DsReadySystemMode( 

int mode) 0: When the cover is open, end the simple callback 


1: After the cover opens or closes, perform an automatic retry 


Explanation 
Sets the action of cover open/close for the simple callback. 





When mode = 0, if the cover is opened during execution, stop processing and end the simple callback. 
Then call the user-specified callback function with intr = DsIDiskError. 


When mode = 1, if the cover is opened or closed, reissue the command with an error and continue 
processing. The user-specified callback function is not called. 


When mode = 1 and the cover is closed, if the disk is not present, the simple callback is completed and the 
user-specified callback function is called with intr = Ds|DiskError. 


Initial value of mode is O. 


The mode is valid until the next time it is set. 


Return value 
Previously updated mode. 


See also 
DsStartReadySystem(), DsEndReadySystem() 
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DsReset 

Reset system. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 


int DsReset(voic) 


Explanation 
Resets the libds system. 


Always use DsReset() when initializing the system in the middle of a program. Dslnit() cannot be used in the 
middle of a program. 


Return value 
1 if the reset was successful, O otherwise. 


See also 
DsInit() 
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DsSearchFile 

Get position and size of CD-ROM file. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 

DsIFILE *DsSearchFile( 

DsIFILE “fo, Pointer to CD-ROM file structure 

char *name) Filename 

Explanation 


Obtains the absolute position (minutes, seconds, sectors) and size of the CD-ROM file specified by name 
and stores the result in the DsIFILE structure pointed to by fp. 


Filenames must be represented by their absolute paths. 


The position data for all the files in the same directory as the file specified by fp is cached in memory. 
Therefore, when DsSearchFile() is performed consecutively for files from a single directory, access is faster 
from the second file on. 








Return value 


0: file not found. 
-1: the read operation on the directory failed for some reason. 
Other: pointer to the retrieved file structure. 
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DsSetDebug 
Set the debug level. 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 


Syntax 


int DsSetDebug( 
int /evel) Debug level 


Explanation 

Sets the debug level for the CD-ROM subsystem to level: 
0: Do not perform any checks 

1: Check primitive commands 


Return value 
Previous debug level. 
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DsShellOpen 

Get the number of times the cover was opened. 
Library Header File Introduced Documentation Date 
libds.lib libds.h 4.0 12/14/98 

Syntax 


int DsShellOpen(voic) 


Explanation 


Obtains the number of times the cover was opened since the program began. The count is initialized to 1 
when the program starts. 





Note: This function returns the correct value only when DsSystemStatus()=DsReady. 


Return value 
Number of times the cover was opened. 


See also 
DsSystemStatus() 
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DsStartReadySystem 
Start the simple callback. 


Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 


Syntax 


int DsStartReadySystem( 
DsIRCB func, Pointer to calloack function 
int count) Retry count (-1: unlimited retries) 


Explanation 

Starts the simple callback. 

When the simple callback is started, a DsIDiskError results in a retry of the last command. 
count is the total number of retries from the point when the system is started. 


The callback function func normally triggers when a data read successfully completes. The only time an 
error makes the function trigger is if the cover is opened or an error is generated after the maximum 
number of retries. 








When a retry is performed, the position from which to re-read is determined by the library, but the callback 
function triggers from the sector following the previous call. Thus, internally, the callback function does not 
need to be aware of the retry. 





This function is always executed from a callback from a corresponding data read (playback) command. 
Executing the function at other times may corrupt the error handling system. 


DsReadyCallback() should be used internally for simple calloack. Simultaneous use from the application is 
not allowed. 


Return value 


1: the function was successful. 
O: the function failed (system has already been started). 


See also 
DsEndReadySystem(), DsReadyCallback() 
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DsStatus 

Get the status of the CD subsystem. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 


u_char DsStatus(voic) 
Explanation 
Obtains the last reported status of the CD subsystem. 


Because updating of the status can sometimes be delayed, in rare cases the value may be different from 
the current CD subsystem status. To wait for any delays to pass, use DsINop to get the most recent 
status. 


Return value 
Status of the CD subsystem. 


See also 
DsCommand)() 
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DsSync 

Check for completion of primitive command. 
Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 

Syntax 

int DsSync( 

int id, Command ID 

u_char *result) Pointer to buffer for storing result (u_char[8}) 

Explanation 


Obtains the execution status of the primitive command specified by id and stores it in the memory area 
pointed to by result. 


The execution status refers to the command corresponding to the command ID that was active when the 
function was called. result is valid only for the return values of DsIComplete or DsIDiskError. 


If id is set to O, the most current result regardless of the type of command can be obtained. 
A certain number of execution results from commands are saved. The maximum number of saved results is 
defined by the DsIMaxRESULTS macro constant. 


Return value 


DslComplete Command has terminated normally. 

DslDiskError Command failed. 

DslNolntr Command has not yet been executed. 

DslNoResult Execution has terminated but the results have already 


been destroyed. 


See also 
DsSyncCallback() 
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DsSyncCallback 
Set Sync Callback function 


Library Header File Introduced Documentation Date 
libs. lib libds.h 4.0 12/14/98 


Syntax 


DsICB DsSyncCallback( 
DsICB func) Pointer to callback function 


Explanation 

Defines func as the Sync callback to be triggered for all command termination and error interrupts. 

If the queue performs retries for commands that generate errors, the Sync callback function is triggered 
after each failure (rather than the individual callback function set for the command itself). 


Return value 
Pointer to previous callback function. 


See also 
DsSync() 
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DsSystemStatus 

Get status of command queue. 
Library Header File Introduced Documentation Date 
libds. lib libds.h 4.0 12/14/98 

Syntax 


int DsSystemStatus(voic) 


Explanation 
Returns the status of the command queue. 





Commands issued when the status is not DslReady are all added to the queue; otherwise, the command is 
executed immediately. 


Return value 


DslReady No command is being executed. 

DslBusy Command is being executed, or command cannot be executed 
(e.g., because cover is open). 

DsINoCD No CD is installed. 

See also 

DsCommand)() 
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Functions 
CheckCallback 
Determine whether the program is executing a callback. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 2.x 12/14/98 
Syntax 


int CheckCallback(void) 


Explanation 
Determines whether the program is currently executing in callback context or normal context. 


Return value 
O:normal context; 1: callback context. 


See also 
ResetC allback() 
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DisableTAP 

Disable communication with the controller 
Library Header File Introduced Documentation Date 
libtap.lib libtap.h 3.6 12/14/98 

Syntax 


void DisableTAP (void) 
Explanation 
Temporarily disables communication with the controller. 


Although StopTAP() deletes the controller handler activated by Vsync interrupts, this function simply skips 
controller communication with a flag operation. 


Although a normal controller communicates via Vsync interrupts, this function is used only with timing 
longer than 1/60 sec when the controller status is not needed. 


See also 
EnableTAP(), StopTAP() 
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EnableTAP 

Enables occurrence of an event. 
Library Header File Introduced Documentation Date 
libtap.lib libtap.h 3.6 12/14/98 

Syntax 


void EnableTAP (void) 


Explanation 

Enables communication with a controller which was disabled with DisableTAP (). 

Although a normal controller communicates via Vsync interrupts, this function is used only with timing 
longer than 1/60 sec when the controller status is not needed. 


See also 
DisableTAP () 
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GetVideoMode 

Get present video signaling system. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 3.1 12/14/98 

Syntax 


long GetVideoM ode(void) 


Explanation 


Returns the present video signaling system set by SetVideoMode(). (If SetVideoM ode() wasn’t called, no 
matter what the machine, it returns MODE_NTSC.) 


Return value 
Video signaling system mode (MODE_NTSC for NTSC; MODE PAL for PAL). 


See also 
SetVideoMode() 


Run-Time Library Reference CONFIDENTIAL 


Controller/Peripherals Library Functions 


InitGUN 
Initialize gun. 
Library Header File Introduced Documentation Date 
libgun.lib libgun.h 3:5 12/14/98 
Syntax 
void InitGUN( 
char *bufA, Controller receive data buffer for port 0 
long lenA, Length in bytes of bufA 
char *bufB, Controller receive data buffer for port 1 
long lenB, Length in bytes of bufB 
char *buf0, char *bufl, Pointer to horizontal/vertical position receive buffer (necessary buffer size is 
len*4+2 bytes) 
long len) Number of gun interrupts allowed between vertical blank periods (20 
maximum) 
Explanation 


Defines the buffers used to receive data from the light gun and other controllers. Standard controller 
information for buttons and analog controllers is returned in bufA and bufB. InitGUN() cannot be used at the 
same time as InitPAD() or InitTAP (). 


As of library v4.0, DMA operations and interrupts are blocked within the gun interrupt handler in order to 
improve the accuracy of the gun. 


The more gun interrupts you specify between VBLANK periods (len), the more processing is required. Set 
len as low as possible to reduce overhead. 


Since the horizontal direction counter value returns the system clock value, multiply the following 
coefficients according to the horizontal direction resolution in order to obtain pixel values: 


Table 12-1: System Clock/Pixel Clock Variable Table 


Mode Horizontal Direction Resolution Coefficient 
NTSC: 
256 0.158532 
320 0.198166 
384 0.226475 
512 0.317065 
640 0.396332 
PAL: 
256 0.157086 
320 0.196358 
384 0.224409 
512 0.314173 
640 0.392717 


[Pixel value] = [Coefficient] x [System Block value] + [Offset] 


See also 
InitP AD() (see libapi), SelectGUN(), StartGUN(), StopGUN(), RemoveGUN () 
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InitTAP 

Initialize controller. 
Library Header File Introduced Documentation Date 
libtap.lib libtap.h 3.4 12/14/98 

Syntax 

void InitTAP ( 

char *bufA, Pointer to receive data buffer 

long lenA, Receive data buffer length (unit: byte) 

char *bufB, Pointer to receive data buffer 

long lenB) Receive data buffer length (unit: byte) 

Explanation 


Registers a receive data buffer for the controller. 


For the format of the receive buffer, see “Receive Buffer Data Format” of Chapter 13 (Controller/P eripherals 
Library) of the Library Overview. 


Please refer to each terminal’s documentation for the physical positioning of the buttons and channels, etc. 
and compatibility. 


See also 
StartTAP (), StopTAP () 
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PadChkMtap 
Check connection with multi tap 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.7 3/6/00 
Syntax 
int PadChkM tap( 
int port) The port number to be checked 
0: port 1 
1: port 2 
Explanation 


Checks to see if a multi tap is connected to the port on the front of the PlayStation. 


Return value 
Other than 0: multi tap is connected 


0: multi tap is not connected 
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PadC hkVsync 

Check communication with controller. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 


int PadChkVsync(void) 


Explanation 


Determines whether communication with the controller has occurred in a frame. Should be called once per 
frame (1/60 sec) during Vsync. 


Return value 
1: Communication with controller took place (regardless of success/failure) 


0: Communication with controller did not take place (or function was called twice or more in a frame) 


See also 
PadEnableCom() 
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PadEnableCom 

Enable/disable communication with the controller. 
Library Header File Introduced Documentation Date 
libpad lib libpad.h 4.2 2/24/99 

Syntax 


unsigned PadEnableCom( 


unsigned mode) Bit 0 is used to enable/disable port 0, and bit 1 is used to 
enable/disable port 1. 1 = enabled; 0 = disabled 


Explanation 

In general, communication with the controller takes place once per frame (1/60th of a second). However, 
when a lower update rate is desired (e.g. when polling for a button press), communication with the 
controller can be temporarily disabled with this function to provide the application with greater processing 
time. 


The vertical retrace interrupt itself is not enabled or disabled, so PadEnableCom() only works between 
PadStartCom() and PadStopCom(). 


Ports 0 and 1 have a default value of "enabled." Calling PadInitDirect(), PadinitMtap(), PadStartCom(), or 
PadStopCom() don’t affect the enable/disable state set by PadEnableCom(). 


If communication is suspended for three seconds or more, the controller is reset. If communication is 
subsequently restarted, the return value from PadGetState() temporarily becomes PadStateDiscon and a 
retry is generated to refetch controller information. For this reason, the return value from PadGetState() 
needs to be monitored so that refetched actuator information can be properly processed. 


Inhibit communication with one port using PadEnableCom(). When the mouse is attached to the inhibited 
port, the controller which was attached to the enabled port will not recognize the invalid state of the mouse. 
Therefore, the same setting of enabling/inhibiting communication should be performed for both ports. 


Return value 
The previous enable/disable state of communication before the function was called. 


See also 
PadStartCom(), PadStopCom() 
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PadEnableGun 

Enable/disable gun interrupts. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 

void PadEnableGun( 

u_char mask) Enable gun interrupts for specific ports (see Explanation) 

Explanation 


Enables gun interrupts when the corresponding mask bit is set to 1: 
Table 12-2 


ma D7 D6 D5 D4 D3 D2 D1 D 


0 
Pot | 0x13. | 0x12. lox loxo |oxo3 loxo2 loxo1 | oxo0 
number 


Specific gun interrupts can be masked off if horizontal and vertical position information is not needed for 
those guns. 


The default setting is mask disabled for all ports. Retrieval of horizontal and vertical position information 
begins when a gun is connected. 


See also 
PadinitGun(), PadRemoveGun() 
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PadGetState 

Get controller connection state. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 2/24/99 

Syntax 

int PadGetState( 

int port) The port number to be checked (see Explanation) 

Explanation 


Checks that the controller is connected, determines when button-press information is valid, and determines 
when information from the actuators is valid. 


port represents the port number to be checked, as follows: 


Table 12-3 
Port 1 Port 2 

Direct connection 0x00 0x10 

Multi Tap A 0x00 0x10 

Multi Tap B 0x01 0x11 

Multi Tap C 0x02 0x12 

Multi Tap D 0x03 0x13 

Return value 
Table 12-4 

Value Macro (libpad.h) Controller connection state 

0 PadStateDiscon Controller disconnected 

1 PadStateFindP ad Find controller connection (checking) 

2 PadStateFindCTP1 Check for connection with a controller that does not 
support the vibration function (including SCPH-1150). 
(Complete the acquisition of controller information) 

4 PadStateR eqInfo Actuator information being retrieved (data being 
retrieved) 

5 PadStateExecCmd Library is communicating with controller 
(e.g. PadSetActAlign()) 

6 PadStateS table Check for connection with a controller that has a 
vibration function (DUAL SHOCK). Retrieval of actuator 
information completed, or library-controller 
communication completed 
(PadSetActAlign(), etc. can be called) 

See also 


PadSetActAlign() 
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PadInfoAct 
Get actuator information. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 3/6/00 
Syntax 
int PadInfoAct( 
int port, Port number of the controller to be checked (see Explanation) 
int actno, Actuator number to be checked (ranging from 0 to total number of mounted 
actuators -1). Set actno to -1 to get the total number of actuators (in this 
case, the third argument term is ignored) 
int term) Information to be checked about actuator 
Explanation 


Obtains the actuator function number, sub-function number, actuator parameter data size, and actuator 


current drain. 


port is the port number of the controller to be checked, as follows: 


Table 12-5 


Direct connection 
Multi Tap A 
Multi Tap B 
Multi Tap C 
Multi Tap D 


Return value 


Port 1 
0x00 
0x00 
0x01 
0x02 
0x03 


Port 2 
0x10 
0x10 
0x11 
0x12 
0x13 


The return value corresponds to the third argument term as follows. 


Table 12-6 
Third argument 
1 


Macro 
InfoActFunc 


InfoActSub 


InfoActS ize 


InfoActC urr 
InfoActSign 


Return value 


Function number 

(1: continuous-rotation vibration) 
Sub-function number 

(When the function number is 1, 1: low- 
speed rotation, 2: high-speed rotation) 
Parameter data length 

(0: 1 bit (ON/OFF only), 1 or greater: 
number of bytes) 

Maximum current drain 

Setting value which puts the actuator 
into a non-drive state 

0: non-drive at 00 

1: non-drive at 0x80, 0x8000, ... (based 
on data size) 


If the parameter data length for an actuator is more than one byte, each of the parameter write offsets for 
that actuator can be set by writing the actuator number in each of the corresponding offsets using 
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PadSetActAlign(). The controller interprets the position of the lowest numbered offset as the high-order byte 
of the parameter. If the actuator number is written such that the data length for the parameter is exceeded, 
the settings beyond the allowed parameter data length are ignored, beginning with the lowest numbered 
offset. 


Note: Up to 60 units of current can be supplied by the main PlayStation® unit. Therefore, the current drain 
of the actuators should be checked to make sure that it does not exceed 60 units. If actuator parameters 
are set so that the 60-unit limit is exceeded, the actuators connected to the larger port numbers are 
ignored (they are forcibly stopped). This is particularly important for applications that use Multi Taps. 


PadInfoAct() always returns a 0 for a controller that does not support the vibration function (including 
SCPH-1150). Even for a controller that has a vibration function (DUAL SHOCK), the return value is 0 as 
long as the state returned from PadGetState() is anything other than PadStateStable (during 

PadStateR eqInfo). When obtaining actuator information, the application should wait for the return value 
from PadGetState() to become PadStateS table. 


See also 
PadInfoComb(), PadInfoMode() 
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PadiInfoComb 

Get information on actuator combinations that can be used simultaneously. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 2/24/99 

Syntax 

int PadinfoComb( 

int port, Port number of the controller to be checked (see Explanation) 

int listno, List number of the combination list to be checked (ranging from 0 to total 


combination list -1). Specify -1 for listno to obtain the total number of 
combination lists. In this case, the offs argument is ignored 


int offs) Offset within the combination list (ranging from 0 to total number of 
actuators contained in the list -1). Specify -1 for offs to obtain the total 
number of actuators contained in the combination list. 
Explanation 
Checks combinations of actuators that can be used simultaneously based on restrictions imposed by the 
physical arrangement of the actuators, etc. 


port is the port number of the controller to be checked, as follows: 


Table 12-7 
Port 1 Port 2 
Direct connection 0x00 0x10 
Multi Tap A 0x00 0x10 
Multi Tap B 0x01 0x11 
Multi Tap C 0x02 0x12 
Multi Tap D 0x03 0x13 
Return value 
Table 12-8 
listno offs Return value 
-1 --- Total number of combination 
lists 
0 to (Total number-1) -1 Total number of actuators 
contained in list number listno 
0 to (Total number-1) 0 to (Total number-1) Actuator number stored at offset 


offs within list number listno. 


Note: PadinfoComb() always returns 0 for a controller that does not support the vibration function 
(including SCPH-1150). Even for a controller that has a vibration function (DUAL SHOCK), the return value 
is 0 as long as the state returned from PadGetState() is anything other than PadStateStable (during 
PadStateR eqinfo). When obtaining information about combinations of actuators that can be used 
simultaneously, the application should wait for the return value from PadGetState() to become 

PadStateS table. 


See also 
PadinfoAct(), PadinfoM ode() 
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PadInfoMode 

Get information about the controller mode. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 3/6/00 

Syntax 

int PadinfoM ode( 

int port, Port number of the controller to be checked (see Explanation) 

int term, Item to be checked 

int offs) The offset in the controller mode ID table containing the desired controller 

mode ID 
Explanation 


Checks the currently active controller mode ID, distinguishes DUAL SHOCK controllers from other 
controllers, and checks the controller mode ID supported by the DUAL SHOCK controller. 


port is the port number of the controller to be checked, as follows: 


Table 12-9 
Port 1 Port 2 
Direct connection 0x00 0x10 
Multi Tap A 0x00 0x10 
Multi Tap B 0x01 0x11 
Multi Tap C 0x02 0x12 
Multi Tap D 0x03 0x13 


When DUAL SHOCK controller SCPH-1200 is connected and PadLoadInfo() is called, initialization 
completes and the return value is as shown below. 


Table 12-10 
Controller information Contents immediately after 
initialization 
Currently active controller mode ID 4 
Currently active controller mode ID (Only for 4 


controllers with a vibration function) 


Total number of controller modes supported by the 
controller 


Controller mode ID table offset for currently active 0 
controller mode ID 


Contents of controller mode ID table See table below 


Table 12-11: Contents of controller mode table ID 


Controller mode ID table offset Controller mode ID 
0 4 
1 7 
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Return value 
The return value corresponds to the second and third arguments(*) in the following manner. 


Table 12-12 
2™ Argument Macro Return value 


1 InfoModeCurlD Currently active controller mode ID. 
Valid range: 4 bits. Game as value of terminal 
type for offset 1 in receive buffer) 

2 InfoM odeCurExID Currently active controller mode ID ona 
controller that has a vibration function. 
Valid range: 16 bits. 
(0 for controllers that do not support the 
vibration function) 


3 InfoM odeC urE xO ffs Offset within the controller mode ID table that 
stores the currently active controller mode ID. 
(0 for controllers that do not support the 
vibration function.) 

4 InfoM odeldTable Controller mode ID stored at the offset 
specified by the third argument offs within the 
controller mode ID table. However, if a 
negative value is specified to the third 
argument offs, this is the total number of 
controller modes which the controller supports. 
(0 for controllers that do not support the 
vibration function.) 


(*): If the second argument has a value other than 4(InfoModeldTable) the third argument offs is ignored. 


When the second argument is 1 (InfoModeCurlD) or 2 (InfoModeCurExID), the function may be called at any 
time, regardless of the value returned by PadGetState(). 


When the second argument is 4 (InfoModeldTable), the return value will be 0 if PadGetState() does not 
return PadStateStable (for PadStateR eqInfo). This is true even if the controller has a vibration function 
(DUAL SHOCK). After calling PadLoadInfo(), the application should wait for the return value from 
PadGetState() to become PadStateS table. 


See also 
PadinfoAct(), PadinfoC omb() 
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Padinit 

Initialize a controller (for prototyping only). 
Library Header File Introduced Documentation Date 
libetc.lib libetc.h 3.0 12/14/98 

Syntax 

void PadInit(mode) Always pass 0 

Explanation 


Initializes the controller. Since this function supports only the 16-button controller, it should be used for 
prototyping purposes only. 


See also 
PadInitDirect(), PadStop() 
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PadinitDirect 


Initialize controller environment (for direct connection to the main PlayStation unit). 


Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 
Syntax 


void PadInitDirect( 
u_char *pad1, 
u_char *pad2) 


Port 1 receive results (34 bytes) 
Port 2 receive results (34 bytes) 


Explanation 
Initializes the control environment for a controller. 


When using this function, other initialization routines such as PadInitMtap(), InitPAD(), InitGUN(), InitTAP (), 
and Padinit() cannot be used. 


In libpad, controller connection state is maintained by the library. If the connection state is invalid, the 
controller isn’t be recognized. Therefore, when a controller is used by both parent and child processes, 
each process must call PadInitDirect(). 


For the format of the receive buffer, see “Receive Buffer Data Format” of Chapter 13 (Controller/P eripherals 


Library) of the Library Overview. 


If a Multi Tap is not used, using this function for initialization reduces program size by about 1.6KB. 


Meaning of analog values: 


Table 12-13 


Device 
Analog controller 


Analog joystick 
Gun controller 


(Namco) 


Mouse 


See also 


Analog value 1 


Position along 
the X axis (right) 
(0 ~80 ~FF) 
Position along 
the X axis (right) 
(0 ~80 ~FF) 
Position along 
the X axis 
Low-order byte 
Displacement 
along the X axis 
(80 ~0 ~ 7F) 


Analog value 2 


Position along 
the Y axis (right) 
(0 ~ 80 ~ FF) 
Position along 
the Y axis (right) 
(0 ~ 80 ~ FF) 
Position along 
the X axis 
High-order byte 
Displacement 
along the Y axis 
(80 ~0 ~7F) 


Analog value 3 


Position along 
the X axis (left) 
(0 ~ 80 ~ FF) 
Position along 
the X axis (left) 
(0 ~ 80 ~ FF) 
Position along 
the Y axis 
Low-order byte 


None 


Padinit(), PadinitMtap(), PadinitGun(), PadStartCom(), PadStopCom() 
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Analog value 4 


Position along 
the Y axis (left) 
(0 ~ 80 ~ FF) 
Position along 
the Y axis (left) 
(0 ~ 80 ~ FF) 
Position along 
the Y axis 
High-order byte 
None 
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Initialize controller environment (for guns that use interrupts). 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 

void PadInitGun( 

u_char *buff, Horizontal/vertical position receive buffer (required buffer size = size*4+2 

bytes) 
int size) Maximum number of gun interrupts for 1Vsync (maximum 20) 
Explanation 


Sets up the horizontal/vertical position receive buffer. Retrieval of the horizontal and vertical positions is 
triggered by an interrupt from the gun. 


In order to improve the accuracy of the gun, interrupts and DMAs are blocked within the interrupt handler. 
Setting a large number of interrupts per 1Vsync consumes 1Hsync of time for each interrupt, so this value 
should be set low. 


Structure of horizontal/vertical position receive buffer: 


Table 12-14 
Offset Contents 
0 Port number for retrieved horizontal/vertical positions 
1 Number of valid horizontal and vertical counters 
2,3 Vertical counter value 0 
4,5 Horizontal counter value 0 
6,7 Vertical counter value 1 
8,9 Horizontal counter value 1 
78,79 Vertical counter value 19 
80,81 Horizontal counter value 19 


(Counter values are half-words (LSB first)) 


The horizontal counter value returns the system clock value. The pixel value can be obtained by multiplying 
by the coefficient corresponding to the horizontal resolution shown in the table below. 


System clock - pixel clock conversion table: 


Table 12-15 

Mode Horizontal resolution Coefficient 

NTSC: 
256 0.158532 
320 0.198166 
384 0.226475 
512 0.317065 
640 0.396332 
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Mode Horizontal resolution Coefficient 
PAL: 
256 0.157086 
320 0.196358 
384 0.224409 
512 0.314173 
640 0.392717 


[Pixel value] = [Coefficient] x [System clock value] + [Offset] 


Horizontal/vertical gun positions are fetched from ports to which a terminal type=3 controller is connected 
and for guns whose interrupts have been enabled by PadEnableGun(). 


Gun horizontal/vertical positions can be fetched during each frame, in sequence, beginning with the 
smallest port number for those ports with guns which are interrupt-enabled. 


Check offset 0 in the horizontal/vertical position receive buffer ("Port number for retrieved horizontal/vertical 
positions") to determine the port number associated with the retrieved horizontal/vertical position. 


PadInitG un() is provided only to initialize the gun interrupt environment. In order to communicate with a gun 
controller, PadInitDirect() or PadInitMtap() must be called first. 


In libpad, gun connection state is maintained by the library. If the connection state is invalid, gun position 
information cannot be obtained. Therefore, as an example, when both parent and child processes use an 
ID=3 gun, each process must call PadInitGun(). 


See also 
PadRemoveGun(), PadEnableGun(), PadInitDirect(), PadInitM tap() 
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PadinitMtap 

Initialize controller environment (for Multi Taps). 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 

void PadInitM tap ( 

u_char *pad1, Port 1 receive result (34 bytes) 

u_char *pad2) Port 2 receive result (34 bytes) 

Explanation 


Initializes the control environment for a controller. If a Multi Tap is connected, it is treated as a Multi Tap. If a 
controller is connected directly to the main PlayStation unit, the structure of the receive buffer is the same 
as when it is initialized with PadInitDirect(). 


When using this function, other initialization routines such as PadinitDirect(), InitPAD(), InitGUN(), InitTAP (), 
and Padinit() cannot be used. 


In libpad, controller connection state is maintained by the library. If the connection state is invalid, the 
controller cannot be recognized. Therefore, when a controller is used by both parent and child processes, 
each process must call PadInitMtap/(). 


For the format of the receive buffer, see “Receive Buffer Data Format” of Chapter 13 (Controller/P eripherals 
Library) of the Library Overview. 


Note: A Multi Tap may not be recognized if a controller is not connected to port A of the Multi Tap. 
Therefore, a controller should always be connected to port A of the Multi Tap. This should also be 
mentioned in the instruction manual. 


See also 
PadInitDirect(), PadInitGun(), PadStartCom(), PadStopCom() 
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PadRead 

Read data from the controller (for prototyping only) 
Library Header File Introduced Documentation Date 
libetc.lib libetc.h 3.0 12/14/98 

Syntax 

u_long PadRead( 

u_short id) Controller ID (unused) 

Explanation 


Reads data from the controller. This function is for prototyping purposes only. 


Return value 
Controller button status. High 2 bytes are pad 2, low 2 bytes are pad 1. 


See also 
Padinit() 
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PadRemoveGun 

Stop retrieval of horizontal/vertical gun position. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 


void PadRemoveGun(void) 


Explanation 
Stops the retrieval of horizontal/vertical gun position information. 


See also 
PadInitG un(), PadEnableGun() 
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PadSetAct 

Set transmit buffer. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 

void PadSetAct( 

int port, Target port number (see Explanation) 

u_char *data, Transmit data buffer 

int len) Length of transmit data buffer (in bytes) 

Explanation 


Registers the transmit data buffer in the library, so it is not necessary to call this function again if the 
transmit buffer doesn't change. When the operation of the actuator changes and the contents of the buffer 
change, the library reads out the buffer every Vsync and automatically transmits the contents to the 
controller. 


port is the target port number, as follows: 


Table 12-16 
Port 1 Port 2 
Direct connection 0x00 0x10 
Multi Tap A 0x00 0x10 
Multi Tap B 0x01 0x11 
Multi Tap C 0x02 0x12 
Multi Tap D 0x03 0x13 


When controlling the DUAL SHOCK actuator, not only must the transmit buffer be specified using 
PadSetAct(), but PadSetActAlign() must also be used to inform the controller of the offset in the transmit 
buffer where the actuator parameters are located. (The calling sequence of PadSetActAlign() and 
PadSetAct() is not specified.) 


The data length that can be handled by the actuator can be determined with PadInfoAct(). For the SCPH- 
1200, the data lengths are 1 bit and 1 byte for actuator numbers 0 and 1, respectively. Thus, the actuator 
can be controlled by using PadSetActAlign() to send the parameter for actuator number 0 at transmit buffer 
offset 0, and the parameter for actuator number 1 at offset 1. In this case, offset 0 would contain a value of 
0 or 1, and offset 1 would contain a value between 0 and 255. 


The actuator is stopped when the parameter value is 0, and rotates faster for larger values. 


Once the actuator parameters have been sent to the controller during a vertical retrace interrupt, the 
actuator continues operating even if communication with the controller is suspended by PadEnableCom() 
or PadStopCom(). However, if communication is suspended for three seconds or more, the controller is 
reset, at which point the actuator stops operating. Even if the interval during which communication is 
suspended is less than three seconds, the actuator temporarily stops operating when PadStartCom() 
reinitiates communication (if communication was suspended with PadStopCom)(), it can only be restarted 
by calling PadStartCom()). 


If communication is suspended for three seconds, or if the actuator is halted due to a PadStartCom() read, 
the value returned from PadState() temporarily becomes PadStateDiscon and a retry is generated to refetch 
controller information. For this reason, the return value from PadGetState() must be monitored so that 
refetched actuator information can be properly processed. 
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If the parameter data length for an actuator is more than one byte, each of the parameter write offsets for 
that actuator can be set by writing the actuator number in each of the corresponding offsets using 
PadSetActAlign(). The controller interprets the position of the lowest numbered offset as the high-order byte 
of the parameter. If the actuator number is written such that the data length for the parameter is exceeded, 
the settings beyond the allowed parameter data length are ignored, beginning with the lowest numbered 
offset. 


For a DUAL SHOCK controller, the offsets in the transmit buffer where actuator parameters are written can 
be specified with PadSetActAlign(). However, with analog controller SCPH-1150, there is a pre-determined 
method for setting up the transmit buffer. The method for setting up the transmit buffer and relevant points 
to be observed are described below. 


Table 12-17 
Offset Contents 
0: target device ID High-order 2 bits: 0x01 
Low-order 6 bits: undefined (vibration device) 
1: transmit data bit 0: 
1 = vibration ON, 
0 = vibration OFF 
remaining bits (bit 7 ~ 1): undefined 
2... : transmit data Always 0x00. Other values: undefined 


Note: The actuator can be turned on only during the 1 Vsync interval before communication with the next 
controller takes place. During the inverval in which the actuator is to be operated, the target device ID 
should be entered in the transmit data buffer and vibrations should be set to ON at each vertical sync 
interrupt. The target device ID is valid when the two high-order bits are set to 01. The remaining bits are 
reserved for the system and should be set to 0. Vibrations are set to ON when the low-order bit of the first 
transmit data byte is set to 1. The remaining bits should be set to 0 as with the target device ID. 


See also 
PadSetActAlign() 
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PadSetActAlign 

Set actuator parameter details to be sent to the controller. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 2/24/99 

Syntax 

int PadSetActAlign( 

int port, Port number of the controller (See Explanation) 

char *data) Actuator parameter transmission details (6 bytes) 

Explanation 


The position in the transmit buffer where the actuator parameters are located is indicated to the controller 
by writing the actuator numbers in the appropriate positions in the 6-byte array. 


port is the port number of the controller to which the actuator parameter details are to be sent: 


Table 12-18 
Port 1 Port 2 
Direct connection 0x00 0x10 
Multi Tap A 0x00 0x10 
Multi Tap B 0x01 0x11 
Multi Tap C 0x02 0x12 
Multi Tap D 0x03 0x13 


In the table shown below, offset 0 of the transmit buffer is used for actuator number 0, and offset 1 is used 
for actuator number 1. The remaining offsets are not used. (The actuator number is entered at positions 
where transmission is desired, and FF is entered at unused positions.) 


Table 12-19 


m (a ES a ee eee 
[Contents [00 for [FF [FPF [FF FC 


When the Controller ID (return value from PadinfoMode(port, InfoModeCurExID, 0)) is different, the number 
of actuators and the type are also different. When calling PadSetActAlign(), the actuator functions from 
PadinfoAct() and the controller ID should be confirmed. 


This function doesn’t accept requests if the library is communicating with the controller. The return value 
should be checked to see if the request was accepted. The request is accepted if PadGetState() returns 
PadStateStable, so the value from PadGetState() can be checked to confirm that the request was 
accepted. However, when PadSetActAlign() and PadS etMainM ode() are called, the result from 
PadGetState() changes immediately from PadStateStable to PadStateExecCmd, and PadSetActAlign() and 
PadSetMainMode() calls are not accepted until three vertical sync interrupts (six for Multi Taps) have 
elapsed. Thus, these two functions cannot be called one after the other. If PadState() is called instead of 
checking the return value, PadGetState() should be called right before calling the functions to confirm that 
the return value is PadStateStable. 


Return value 


A 1 is returned if the actuator parameter details request is accepted. 0 is returned if the request is not 
accepted. 


See also 
PadGetState(), PadSetAct(), PadSetMainMode() 
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PadSetMainMode 
Switches / locks the controller mode selector. 
Library Header File Introduced Documentation Date 
libpad lib libpad.h 4.2 12/14/98 
Syntax 
int PadSetMainMode( 
int port, Port number for which the controller mode is to be switched (see 
Explanation) 
int offs, The controller mode ID table offset which contains the controller mode to be 
switched 
int lock) If bit 1 is set to 0, the locked/unlocked state of the selector button is kept in 


its current state. If bit 1 is set to 1 and bit 0 is set to 0, the selector button is 
unlocked. If bit 1 is 1 and bit 0 is 1, the selector button is locked. 
Explanation 


Selects the controller mode and switches between locked and unlocked settings for the controller mode 
selection button on the main controller unit. 


port is th port number for which the controller mode is to be switched, as follows: 


Table 12-20 
Port 1 Port 2 
Direct connection 0x00 0x10 
Multi Tap A 0x00 0x10 
Multi Tap B 0x01 0x11 
Multi Tap C 0x02 0x12 
Multi Tap D 0x03 0x13 


When this function is called and the controller mode is changed, controller information is retrieved. 
Therefore, the value returned from PadGetState() needs to be monitored so that actuator information can 
be properly refetched. 


This function doesn’t accept requests if the library is communicating with the controller. The return value 
should be checked to see if the request was accepted. The request is accepted if PadGetState() returns a 
PadStateStable, so the value from PadGetState() can be checked to confirm that the request was 
accepted. However, when PadSetMainMode() or PadSetActAlign() is called, the result from PadGetsState() 
changes immediately from PadStateStable to PadStateExecCmd, and PadSetActAlign() and 
PadSetMainMode() don’t accept requests. Therefore, these two functions cannot be called one after the 
other. When PadState() is checked instead of the return value, PadGetState() must be checked right before 
Calling the functions. 


Return value 
1 when a controller mode setting request was accepted. 0 if the request was not accepted. 


See also 
PadGetState(), PadSetActAlign() 
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PadStartC om 

Start reading from controller. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 


void PadStartCom(void) 


Explanation 
Initiates a controller read operation triggered by a vertical retrace interval interrupt. 


See also 
PadInitDirect(), PadinitMtap(), PadStopCom(), PadEnableCom() 
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PadStop 

Halt controller (for prototyping only) 
Library Header File Introduced Documentation Date 
libetc.lib libetc.h 2.x 12/14/98 

Syntax 


void PadStop(void) 


Explanation 
Halts all currently connected controllers. 
When processing is complete, it is necessary to call this function without fail and halt the controller driver. 


This function is for prototyping purposes only. 


See also 
Padinit() 
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PadStopCom 

Stop controller read. 
Library Header File Introduced Documentation Date 
libpad.lib libpad.h 4.2 12/14/98 

Syntax 


void PadStopCom(void) 


Explanation 


Stops a controller read operation. (Stops handling all vertical interval interrupts related to controller 
services.) 


See also 
PadInitDirect(), PadinitMtap(), PadStartCom(), PadEnableCom() 
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RemoveGUN 

Remove gun driver. 
Library Header File Introduced Documentation Date 
libgun.lib libgun.h 3.6 12/14/98 

Syntax 


void RemoveG UN (void) 


Explanation 
Removes the gun driver registered in InitGUN(). 


See also 
InitGUN(), StartGUN(), StopGUN(), SelectGUN(), RemoveGUN() 
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ResetC allback 

Initialize all callbacks. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 3.0 12/14/98 

Syntax 


void ResetCallback(void) 


Explanation 


Initializes all system callbacks. Sets all callback functions to 0 (unregistered), and after securing the interrupt 
context stack, sets up the environment for accepting interrupts. 


ResetCallback() must be called after program boot, before any other processing is performed. 

The environment initialized by ResetCallback() remains valid until StopCallback() is called. 

It is acceptable to continuously call ResetCallback() without StopCallback(). However, the second and 
subsequent calls are ignored. 


See also 
StopCallback() 
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RestartC allback 

Restart a halted callback. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 3.2 12/14/98 

Syntax 


int RestartCallback(void) 

Explanation 

Restores the halted call-back to the status immediately prior to when it was halted. 

Differs from ResetCallback() in that the call-back functions and call-back stack are not initialized. 
ResetCallback() must be executed before executing RestartCallB ack(). 

The environment initialized by RestartCallback() is valid until StopCallback() is called. 

There is no problem even if RestartC allback() is successively called without inserting StopCallback(), but 


calls from the second one onwards are ignored. 


Return value 
Used by system only. 


See also 
StopCallback() 
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SelectGUN 


Select gun. 


Library Header File Introduced Documentation Date 
libgun.lib libgun.h 3:5 12/14/98 

Syntax 

void SelectGUN( 

int ch, Gun channel (0 or 1) 

u_char mask) Interruptmask setting (0: interrupts prohibited, 1: interrupts permitted) 

Explanation 

Sets the interrupt mask for the gun. 


It is not possible to disable interrupts for two masks at the same time. 


See also 
InitGUN(), StartGUN(), StopGUN(), RemoveGUN() 
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SetVideoMode 

Declare current video signaling system. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 3.1 12/14/98 

Syntax 

long SetVideoM ode( 

long mode) Video signaling system mode 

Explanation 


Declares the video signaling system indicated by mode to the libraries (MODE_NTSC for NTSC and 
MODE PAL for PAL). 


Related libraries will conform to the actions of the declared video signaling system environment. 


Should be called in advance of all library functions. 


Return value 
Previously-set video signaling system mode. 


See also 
GetVideoMode() 


CONFIDENTIAL Run-Time Library Reference 


12-38 Controller/P eripherals Library Functions 


StartGUN 

Start controller reading. 
Library Header File Introduced Documentation Date 
libgun.lib libgun.h 3.6 12/14/98 

Syntax 


long StartGUN (void) 


Explanation 
Starts controller reading at Vsync interrupt. 


Return value 
1 if successful; 0 on failure. 


See also 
InitGUN(), StopGUN(), SelectGUN(), RemoveGUN() 
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StartTAP 

Start controller reading. 
Library Header File Introduced Documentation Date 
libtap.lib libtap.h 3.4 12/14/98 

Syntax 


void StartTAP (void) 


Explanation 
Starts controller reading at Vsync interrupt. 


See also 
InitTAP () 
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StopC allback 

Stop all callbacks. 
Library Header File Introduced Documentation Date 
libetc. lib libetc.h 3.0 12/14/98 

Syntax 


void StopCallback(void) 


Explanation 
Stops all system callbacks. 


Before terminating programs, StopCallback() can be called to disable all interrupts. 


See also 
RestartC allback() 
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StopGUN 

Halt controller reading. 
Library Header File Introduced Documentation Date 
libgun.lib libgun.h 3.6 12/14/98 

Syntax 


void StopGUN(void) 


Explanation 
Halts the controller reading. Does not prohibit interrupts. 


See also 
InitTAP (), StartGUN(), SelectGUN(), RemoveGUN() 
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StopTAP 

Halt controller reading. 
Library Header File Introduced Documentation Date 
libtap.lib libtap.h 3.4 12/14/98 

Syntax 


void StopTAP (void) 


Explanation 
Halts the controller reading. Does not prohibit interrupts. 


See also 
InitTAP () 
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_comb._control 


Link cable driver control. 


Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 3.0 12/14/98 

Syntax 

long _comb_control( 

u_long cmd Command 

u_long arg Subcommand 

u_long param) Argument 

Explanation 


Offers the same functionality as ioctl() to an SIO device. 


All the macros in this chapter are versions of this command. 


Table 13-1: _comb_control() Command Summary 


arg Function 

Returns the serial controller status (seeTable 13-2) 
Returns the control line status (see Table 13-3) 
Returns the communication mode (see Table 13-4) 
Returns the communication rate in bps 

Returns the "unit-number of characters for receiving” 
Returns the amount of remaining data (bytes) from 
asynchronous input/output during processing 

If the param is O it is asynchronous write, if 1 it is 
asynchronous read 

O 6 Returns an asynchronous input/output request 
whether it registered or not 

If it has been registered, it will return 1. Others will 
return O. 

If the param is O, it is asynchronous write, if 1 it is 
asynchronous read 





3 
a 
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1 O System reserved 

1 1 Sets the value of param as the control line status (*2) 

1 2 (Reserved) 

1 3 Sets the value of param as the communication rate by 
bps 

1 4 Sets the value of param as the "unit-number of 
characters for receiving" 

2 0 Resets the serial controller 


Controller status, communication mode and 
communication speed are saved 

2 1 Clears the bits related to the driver status error. 
Includes a function which indicates the completion of 
the interrupt processing to the driver 








2 2 Cancels the asynchronous writing 
2 3 Cancels the asynchronous reading 
3 O When param is 1 RTS is made 1 
When param is 0, RTS is made O 
3 1 If (CTS==1) 1 is returned, the others return O 
4 O The param value is considered to be the pointer to the 





function and is registered as the pointer to the wait 
callback function 

The callback function pointer values up to that point 
are returned 





CONFIDENTIAL Run-Time Library Reference 


13-4 Link Cable Library Functions 


Table 13-2: Driver Status 





bit 


Contents 





31-10 


O-H-NWKOONOO 


Undefined 

1: Interrupt is ON 

1: CTS is ON 

1: DSR is ON 

Undefined 

1: Frame error occurrence 

: Overrun error occurrence 

: Parity error occurrence 

: No sending data 

: Possible to read the receiving data 
: Possible to write the sending data 








Table 13-3: Control Line Status 

















bit Contents 
31-2 Undefined 
1 1: RTS is ON 
0) 1: DTR is ON 
Table 13-4: Communication Mode 
bit Contents 
31-8 Undefined 
7,6 Stop bit length 
01:1 
10:1.5 
11:2 
5 Parity check(2) 1: odd number O: even 
number 
4 Parity check(1) 1: enabled 
8,2 Character length 
00:5 bits 
01:6 
10:7 
11:8 
1 1 at all times 
0 O at all times 





Return value 


Depends on the control command cmd. 
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AddCOMB 


Initialize link cable driver. 


Library Header File Introduced Documentation Date 
libcomb.|ib libcomb.h 3.0 12/14/98 


Syntax 
void AddCOMB(\(voic) 


Explanation 
Initializes the link cable driver. 


See also 
DelCOMB( 
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ChangeClearS!IO 

Clear interrupt from expanded SIO in the driver. 
Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 3.0 12/14/98 

Syntax 

void ChangeClearSIO( 

long val Interrupt cause clear flag 

Explanation 


If val is non-O, an interrupt from an expansion SIO in the driver is cleared. This is used only when other 
expansion SIO drivers are also present. 
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DelCOMB 


Remove link cable driver from kernel. 


Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 3.0 12/14/98 


Syntax 
void DelCOMB(voic) 


Explanation 
Removes link cable driver from kernel. 


See also 
AddCOMB() 
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CombAsyncRequest 

Get asynchronous communication request status. 
Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 

Syntax 

long CombAsyncRequest( 

long param) O: asynchronous write, 1: asynchronous read 

Explanation 


Determines whether an asynchronous input/output request has been made. 


This macro is quivalent to _comb_control (0, 6, param). 


Return value 
1 if request has been made; O otherwise. 
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CombBytesRemaining 

Get remaining transmit or receive data. 
Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 

Syntax 

long CombBytesRemaining( 

long param) O: asynchronous write, 1: asynchronous read 

Explanation 


Gets the remaining data count from the asynchronous read or asynchronous write being processed. 


This macro is equivalent to _comb_control (0, 5, param). 


Return value 
The number of bytes remaining. 


See also 
_comb_control() 
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CombBytesToRead 

Get number of bytes left to receive. 
Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 

Syntax 


long CombBytesToRead(voia) 


Explanation 
Obtains the number of bytes left in the current asynchronous read operation. 


This macro is equivalent to _comb_control (0, 5, 1). 


Return value 
The number of bytes remaining. 


See also 
_comb_control() 
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CombBytesToWrite 

Get number of bytes left to send. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombBytesToWrite(voia) 


Explanation 
Obtains the number of bytes remaining in the current asynchronous write operation. 


This macro is equivalent to _comb_control (0, 5, 0). 


Return value 
The number of bytes remaining. 


See also 
_comb_control() 
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CombCancelRead 

Cancel asynchronous read. 
Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 

Syntax 


long CombCancelRead(voic) 


Explanation 
Cancels current asynchronous read operation. 


This macro is equivalent to _comb_control (2, 3, O). 


Return value 
0. 


See also 
_comb_control() 
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CombCancelWrite 

Cancel asynchronous write. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombCancelWrite(voic) 


Explanation 
Cancels current asynchronous write operation. 


This macro is equivalent to _comb_control (2, 2, O). 


Return value 
0. 


See also 
_comb_control() 
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CombControlStatus 

Get control line status. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombControlStatus(voic) 


Explanation 
Obtains the control line status. 


This macro is equivalent to _comb_control (0, 1, 0). 
Return value 
The control line status. Bit fields are as follows: 


Table 13-5: Control Line Status 








bit Contents 

31-2 undefined 
1 1: RTS on 
0 1: DTR on 





See also 
_comb_control() 


Run-Time Library Reference CONFIDENTIAL 


Link Cable Library Macros 13-15 


CombCTS 


Get status of CTS signal. 


Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 


Syntax 
long CombCTS(voic) 


Explanation 
Obtains the state of the serial controller CTS bit. 


This macro is equivalent to _comb_control (3, 1, 0). 


Return value 
1 if CTS is 1; O otherwise. 


See also 
_comb_control() 
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CombGetBPS 


Get communication speed. 


Library Header File Introduced Documentation Date 
libcomb. lib liocomb.h 4.2 12/14/98 


Syntax 
long CombGetBPS(voic) 


Explanation 
Obtains the communication speed (in bps). 


This macro is equivalent to _comb_control (0, 3, 0). 


Return value 
The communication speed (in bps). 


See also 
_comb_control() 
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CombGetMode 
Get communication mode. 
Library Header File Introduced Documentation Date 
libcomb.|ib libcomb.h 4.2 12/14/98 
Syntax 
long CombGetMode(voic) 
Explanation 
Obtains the communication mode. 
This macro is equivalent to _comb_control (0, 2, O). 
Return value 
The communication mode. 
Table 13-6: Communication Mode 
bit Contents 
31-8 undefined 
7,6 stop bit length 
01: 1 
10: 1.5 
11:2 
5 parity2 1:0dd O:even 
4 parity1 1:enabled 
8,2 character length 
00: 5 bits 
01:6 
10: 7 
11:8 
1 always 1 
(0) always O 





See also 
_comb_control() 
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CombGetPacketSize 

Get receive packet size. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombGetPacketSize(voia) 


Explanation 
Obtains the receive packet size. 


This macro is equivalent to _comb_control (0, 4, 0). 


Return value 
The receive packet size. 


See also 
_comb_control() 
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CombReset 

Initialize the serial controller. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombReset(voia) 


Explanation 
Initializes the serial controller. Controller status, communication mode and communication speed remain 
unchanged. 


This macro is equivalent to _comb_control (2, O, O). 


Return value 
0. 


See also 
_comb_control() 
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CombResetError 

Initialize error flags. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombResetError(voic) 


Explanation 
Clears error-related bits from driver status. 


This macro is equivalent to _comb_control (2, 1, 0). 


Return value 
0. 


See also 
_comb_control() 
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CombResetVBLANK 

Reset vertical blanking signal. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 

long CombResetVBLANK(voia) 

Explanation 


Resets the vertical blanking signal. 


This macro is equivalent to _comb_control (5, O, 0). 


Return value 
0. 


See also 
_comb_control() 
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CombSetBPS 


Set communication speed. 


Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 


Syntax 


long CombSetBPS( 
long bps) Communication speed (in bps) 


Explanation 


Sets the communication speed. bps must be in the range 9600 - 2073600 and evenly divisible into 
2073600. If asynchronous write is used, the maximum communication speed is 57600 bps. 


This macro is equivalent to _comb_control (1, 3, Ops). 


Return value 
O. 


See also 
_comb_control() 
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CombSetControl 


Set control line status. 


Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 


Syntax 


long CombSetControl( 
long val Control line status 


Explanation 
Sets the control line status. 


Table 13-7: Control Line Status 








bit Contents 
31-2 unused 

1 1: RTS on 
0 1: DTR on 





This macro is equivalent to _comb_control (1, 1, vai). 


Return value 
O; 


See also 
_comb_control() 
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CombSetMode 


Set communication mode. 


Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 


Syntax 


long CombSetMode( 
long mode) Communication mode 


Explanation 
Sets the communication mode. 


This macro is equivalent to _comb_control (1, 2, mode). 


Table 13-8: Communication Mode 











bit Contents 
31-8 Unused 
7,6 stop bit length 
01:4 
10: 1.5 
11:2 
5 Parity2 1: odd 0: even 
4 Parity! 1: enabled 
8,2 Character length 
00: 5 bits 
01:6 
10: 7 
11:8 
1 Always 1 
O Always O 
Return value 
0. 
See also 


_comb_control() 
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CombSetPacketSize 

Set receive packet size. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 

long CombSetPacketSize( 

long size) Packet size (1, 2, 4, or 8) 

Explanation 


Sets the receive packet size, which sets the byte count used for generating interrupts in asynchronous 
communication. For example, if the receive packet size is set to 4, the serial controller generates an 
interrupt after every four bytes of data received. A large packet size lowers the frequency of interrupts, thus 
improving overall system performance. 








Note: When sending data asynchronously, the packet size must be set to 1, since only 1 byte can be sent 
at a time. 


This macro is equivalent to _comb_control (1, 4, size). 


Return value 
0. 


See also 
_comb_control() 
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CombSetRTS 
Set RTS signal. 


Library Header File Introduced Documentation Date 
libcomb.lib libcomb.h 4.2 12/14/98 


Syntax 
long CombSetRTS(voiac) 


Explanation 
Sets the RTS bit in control line status to 1. 


This macro is equivalent to _comb_control (3, O, 1). 


Return value 
0. 


See also 
_comb_control() 
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CombSioStatus 

Get serial controller status. 
Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 

Syntax 


long CombSioStatus(voic) 


Explanation 
Obtains serial controller status. 


This macro is equivalent to _comb_control (O, O, 0). 


Return value 
The serial controller status. Bit fields are: 


Table 13-9: Serial Controller Status 


Bit Contents 

31-10 undefined 

1: interrupts on 

1: CTS is on 

1: DSR is on 

undefined 

1:frame error generated 
1:overrun error generated 
1:parity error generated 
1:no data to transmit 
1:receive data available 
1:transmit data available 








OFNWAUODNOOO 








See also 
_comb_control() 
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CombWaitCallback 


Set wait callback function. 


Library Header File Introduced Documentation Date 
libcomb. lib libcomb.h 4.2 12/14/98 


Syntax 


long CombWaitCallback( 
long func) Pointer to the wait callback function 


Explanation 
The value of func is entered as a pointer to the wait callback function. 


This macro is equivalent to _comb_control (4, O, func). 


Return value 
The value of the previous callback function. 


See also 
_comb_control() 
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SsSeqPlayPtoP 
SsSeqReplay 
SsSeqSetAccelerando 
SsSeqSetCrescendo 
SsSeqSetDecrescendo 
SsSeqSetNext 
SsSeqSetRitardando 
SsSeqSetVol 
SsSeqskip 
SsSeqStop 
SsSetAutoKeyOffMode 
SsSetCurrentPoint 
SsSetLoop 
SsSetMarkCalloack 
SsSetMono 
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SsSetReservedVoice 
SsSetRVol 
SsSetSerialAttr 
SsSetSerialVol 
SsSetStereo 
SsSetTableSize 
SsSetTempo 
SsSetTickCalloack 
SsSetTickMode 
SsSetVoiceMask 
SsSetVoiceSettings 
SsStart 

SsStart2 
SsUnBlockVoiceAllocation 
SsUtAllKeyOff 
SsUtAutoPan 
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SsUtChangeADSR 
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SsUtFlush 
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SsUtKeyOff 
SsUtKeyOffV 
SsUtKeyOn 
SsUtKeyOnV 
SsUtPitchBend 
SsUtReverbOff 
SsUtReverbOn 
SsUtSetDetVVol 
SsUtSetProgAtr 
SsUtSetReverbDelay 
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ProgAtr 
Program header. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 
Structure 
typedef struct ProgAtr { 
u_char tones; Number of VAG attribute sets contained in the program 
u_char mvol; Master volume for the program 
u_char prior; Program priority (0-15) 
u_char mode; Sound source mode 
u_char mpan; Program pan 
char reservedO; Reserved by the system 
short attr; Program attribute 
u_long reserved; Reserved by the system 
u_long reservea2; Reserved by the system 


} 
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SndRegisterAttr 
SPU register attributes. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 4.1 12/14/98 
Structure 


struct SndRegisterAttr { 
SndVolume2 volume; 


Volume data for left and right channels 














short pitch; Pitch rate at which to play back waveform data 
short mask; Bitfield designating which attributes to set 
short addr; Waveform data start address 
short adsr1; Bitfield for setting adsr information (see Explanation) 
short adsr2; Bitfield for setting adsr information (see Explanation) 
} SndRegisterAttr; 
Explanation 
This structure is used in the function SsQueueRegisters() to set SPU voice information. 
adsr1: 
15 14 9 8 5 4 0 
| | | | | | | 
ar_m: attack rate mode 0 = linear, 1 = exponential 
ar: attack rate 
dr: decay rate 
sil? sustain level 
adsr2 : 
15 14 13 12 6 5 4 0 
| | | | | | l l | 
sr_m sustain rate mod 0 = linear, 1 = exponential 
sr_s sustain rate sign 0 = positive, 1 = negativ 
sr: sustain rate 
rr_m: release rate mod 0 = linear, 1 = exponential 
ries release rate 


Note: Bit 13 is unused 


See also 


SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), SsGetActualProgFromProg(), 
SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), SsSetVoiceSettings(), 
SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SndVoiceStats 
Internal libsnd voice variables. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 
Structure 
struct SndVoiceStats { 
short vagld; VAG number pointed to by tone information (1-254) 
short vabla; VAB number containing tone information (0-15) 
u_short pitch; Playback rate of voice 
short vol; Volume of voice (0-127). Not valid for 3D sound input 
char pan; Voice pan (0-127; O = left, 64 = center, 127 = right) . Not valid for 3D sound 
input 
short note; Note at which tone information keyed on 
short tone; Tone number (0-15) 
short prog_num; Program number containing tone information (0-127) 
short prog_actual; The “real” program number within which the tone information resides. 
} SndVoiceStats; 
Explanation 


This structure is used to fill the internal libsnd voice structures in the function SsSetVoiceSettings\(). 


prog_actual is only incremented by valid programs (programs containing one or more tones) and so may 
differ from prog_num. Example: In a VAB with valid programs 0-10 and 100-127, the prog_num of program 
127 = 127, while the prog_actual of program 127 = 38. Used to calculate offset in VAB header of tone 
information. 


See also 


SndRegisterAttr(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn\(), SsQueueRegisters(), SsQueueReverb\(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SndVolume 


Volume. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Structure 


typedef struct 

SndVolume { 
u_short /eft; L channel volume value, O - 127 
u_short right; R channel volume value, O - 127 


} 
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SndVolume2 


Volume-greater range. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 4.1 12/14/98 


Structure 
struct SndVolume2 { 
short /eft; Left volume value, -0x4000 ~ Ox3fff 
short right; Right volume value, -0x4000 ~ Ox3fff 
} SndVolume2; 


Explanation 


This structure allows for a greater range of volume inputs, including negative volumes, when used with the 
libsnd keyon emulation series: SsBlockVoiceAllocation() -> SsAllocateVoices() -> SsSetVoiceSettings() -> 
SsQueueRegisters() -> SsQueueKeyOn() -> SsQueueReverb() -> SsUnBlockVoiceAllocation(). 


See also 


SndRegisterAttr(), SndVoiceStats(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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VabHdr 


Bank header. 


Library 
liosnd.lib 


Structure 

typedef struct VabHar { 
long form; 
long ver; 
long id; 
u_long fsize; 
u_short reserved0; 
u_short ps; 
u_short ts; 
u_short vs; 
u_char mvol; 
u_char pan; 
u_char atir7; 
u_char atir2; 
u_long reserved7; 


Explanation 


Header File Introduced Documentation Date 
liosnd.h 2.X 12/14/98 


Format name (always 'VABp’') 

Format version number 

Bank (VAB) number 

Bank file size 

Reserved by the system 

Total number of programs contained in the bank 
Total number of tones contained in the bank 
Number of VAGs contained in the bank 

Master volume 

Master pan level 

Bank attribute 1 that can be defined by the user 
Bank attribute 2 that can be defined by the user 
Reserved by the system 











The VAB bank header contains information, such as sound source data set size and sound source 
numerals, that is used at the time of execution. 


When SsVabOpenHead)\) is called, it is read by the system and wave form data is generated in the SPU’s 
local memory. Also, volume setting and panning setting are referred at the time of voice allocation. 





Information about VAB, the program and each VAG header can change at the time of execution by the 
user, and the attribute value is reflected in the voice application after the next KEY ON. 
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VagAtr 


Waveform header. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 
Structure 
typedef struct VagAtr { 
u_char prior; Priority (0-15) 
u_char mode; Sound source mode (Bit values O: normal, 4: reverb) 
u_char vol; Volume (0-127, O:min, 127:max) 
u_char pan; Pan pot (0-127, O:left, 63:center, 127:right) 
u_char center; Center note (0-127) 
u_char shift; Pitch correction (0-127, in cents) (center note fine tune) 
u_char min; Minimum note limit 
u_char max; Maximum note limit 
u_char vibW; Vibrato width (0-127 over one octave) (not implemented) 
u_char vibT; Period of vibrato cycle (in ticks) (not implemented) 
u_char porW; Portamento width (not implemented) 
u_char porT; Period of portamento duration (in ticks) (not implemented) 


u_char pbmin; 
u_char pbmax; 


u_char reserved; 
u_char reserved2; 


u_short adsr7; 
u_short adsr2; 
short prog; 

short vag; 

short reservea/4]; 


Minimum pitch bend limit 

Maximum pitch bend limit 

Reserved by the system 

Reserved by the system 

Set ADSR value 1 

Set ADSR value 2 

Master program containing the VAG attribute 
VAG’s ID number utilized by the VAG attribute 
Reserved by the system 
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_SsFCALL 
Function table type referenced in SsSeqOpenu() and SsSepOpenu(). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.6 12/14/98 
Structure 
typedef struct { 
void (*noteon) (); 
void (“programchange) (); 
void (“pitchbend) (); 
void (*metaevent) (); 
void (*control[13}) 0; 
void (*ccentry/20)) (); 
}_SsFCALL; 
Members 
All members hold pointers to low-level MIDI functions. 
Table 14-1 
Member Pointer to 
_SsNoteOn 
_SsSetProgramChange 
_SsSetPitchBend 
_SsGetMetaEvent 
Specified when using _SsSetContro/Change 
Control Change 
Control Change#1 (Bank _SsContBankChange 
Change) 
Control Change #6 (Data _SsContDataEntry 
Entry) 
Control Change #7 (Main _SsContMainVol 
Volume) 
Control Change #10 (Pan _SsContPanpot 
Pot) 
Control Change #11 _SsContExpression 
(Expression) 
control [CC_DAMPER] _SsContDamper Control Change #64 
(Damper pedal) 
control [CC_NRPN1] _SsContNrpn1 Control Change #98 
(NRPN) 
control [CC_NRPN2] _SsContNrpn2 Control Change #99 
(NRPN) 
control [CC_RPN1] _SsContRon1 Control Change #100 
(RPN) 
control [CC_RPN2] _SsContRon2 Control Change #101 
(RPN) 
control [CC_EXTERNAL] _SsContExternal Control Change #91 
(External Effect Depth) 
control [CC_RESETALL] _SsContResetAll Control Change #121 
(Reset All) 
ccentry [DE_PRIORITY] _SsSetNrpnVabAttrO priority 
ccentry [DE_MODE] _SsSetNronVabAttr1 mode 
ccentry [DE_LIMITL] _SsSetNronVabAttr2 limit low 
ccentry [DE_LIMITH] _SsSetNronVabAttr3 limit high 
ccentry [DE_ADSR_AR_L] SsSetNronVabAttr4 ADSR (AR-L) 
ccentry [DE_ADSR_AR_E] SsSetNronVabAttrd ADSR (AR-E) 
ccentry [DE_ADSR_DR] _SsSetNrpnVabAttr6 ADSR (DR) 
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Member Pointer to 

ccentry [DE_ADSR_SL] _SsSetNronVabAttr7 ADSR (SL) 

ccentry [DE_LADSR_SR_L] SsSetNronVabAttr8 ADSR (SR-L) 

ccentry [DE_ADSR_SR_F] SsSetNronVabAttr9 ADSR (SR-E) 

ccentry [DE_ADSR_RR_L] SsSetNronVabAttr1 0 ADSR (RR-L) 

ccentry [DE_LADSR_RR_F] SsSetNronVabAttr1 1 ADSR (RR-E) 

ccentry [DE_ADSR_SR] _SsSetNronVabAttr12 ADSR (SR) 

ccentry [DE_VIB_TIME] _SsSetNronVabAttr13 vibrate time (no support) 

ccentry _SsSetNrpnVabAttr14 portamento depth (no 

[DE_PORTA_DEPTH] support) 

ccentry [DE_REV_TYPE] _SsSetNrpnVabAttr15 reverb type 

ccentry [DE_REV_DEPTH] = _SsSetNrpnVabAttr16 reverb depth 

ccentry [DE_ECHO_FB] _SsSetNronVabAttr1 7 echo feedback 

ccentry _SsSetNrpnVabAttr18 echo delay 

[DE_ECHO_DELAY] 

ccentry [DE_DELAY] _SsSetNronVabAttr19 delay time 
Explanation 


The functions SsSeqPlay() and SsSepPlay() analyze the MIDI status data and call low-level functions. When 
calling SsSeqOpen() or SsSepOpen\), all the low-level functions are linked in, even though an application 
won't necessarily use them all. 


The new functions SsSeqOpenu() and SsSepOpenu() have been added to replace SsSeqOpen() and 
SsSepOpen() respectively. With these functions, all the low-level functions are in a jump table, so the user 
can select only the desired function groups. Unnecessary functions aren’t linked, so code size is reduced. 





The _SsFCALL structure defines this function table. Low-level functions that have pointers assigned to 
them are linked in. Low-level functions can be eliminated by not setting the member. 





To determine which functions will be called by a MIDI sequence, you can use a test program. This is 
necessary because, ilf a MIDI sequence calls a low-level function which hasn’t been linked in, a BUS 
ERROR results. Set all pointers for low-level functions to the correspondingly named dmy_Ss...() function. 
Each low-level function called by the MIDI sequence outputs a message via printf(). 








SsFCALL is the name of the actual liosnd variable that must be used by the programmers to link the low- 
level MIDI functions. 


See also 
dmy_Ss...(), SsSeqOpenJ(), SsSepOpenu() 
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dmy_Ss... 
Test function for low-level MIDI jump table. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.6 12/14/98 

Syntax 

void dmy_Ss...(void) 


Explanation 
Hook these dummy functions into the libsnd variable SsFCALL (structure type _SsFCALL). 


Ex: SsFCALL.noteon = (void (*)()) dmy_Ss_NoteOn(); 


When these functions are called for the first time, the name of the low-level MIDI function is output by 
printf). After all of the low-level MIDI functions that need to be called by your program have been 
determined, replace the registered dmy_Ss...() calls with the appropriate _Ss_...() calls. Unused dmy_Ss...() 
should be deleted. 








This function is provided for debugging. 
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SsAllocateVoices 

Compare priorities of a number of voices and allocate them where possible. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

long SsAllocateVoices( 

u_char voices, The desired number of voices required to be keyed on simultaneously 

u_char priority) Priority of the desired voices 


Range: 0-127, with O being lowest priority and 127 being highest priority 


Explanation 

Emulates the libsnd voice allocation system, but allows more than one voice to be allocated simultaneously. 
Searches through all 24 SPU voices for SPU voices in the state SPU_OFF, ENV_OFF (that is, SPU voices 
which are not currently sounding). If there are fewer SPU voices in a state of SPU_OFF, ENV_OFF than the 
total number of desired voices, the levels of voice priority are compared, and the lowest priority SPU voice 
number is allocated for the desired voices (if the lowest priority is less than the value set in priority). 


Where the priorities are equivalent, the SPU voice number with the lowest envelope is allocated to the 
desired voices. 














Where the priorities and envelope size are the same, the oldest SPU voices are allocated to the desired 
voices. 


This function should only be used as part of the series: SsBlockVoiceAllocation() -> SsAllocateVoices()-> 
SsSetVoiceSettings()-> SsQueueRegisters()-> SsQueueKeyOn()-> SsQueueReverb() -> 
SsUnBlockVoiceAllocation() 


Return value 

A bifield specifying which voices were allocated for key on. To determine if a voice was allocated, AND the 
return value with the mask for a particular voice (GPU_OOCH ...SPU_23CH). If the value is non-zero, the 
voice was allocated. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsBlockVoiceAllocation(), SsGetActualProgFromProg(), 
SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), SsSetVoiceSettings\(), 
SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SsBlockVoiceAllocation 
Block voice allocation system used by SsUtKeyOn(), SsUtKeyOnV(), and MIDI key on commands. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 4.1 12/14/98 
Syntax 


char SsBlockVoiceAllocation(void) 


Explanation 

Blocks the voice allocation system for libsnd functions SsUtKeyOn() and SsUtKeyOnV(). Once this function 
is called, those functions will return -1. MIDI key on commands are also blocked until 
SsUnBlockVoiceAllocation() is called, in order to ensure proper key on. 





The time spent until SsUnBlockVoiceAllocation() should be short, in order to reduce missed key on 
commands. 


This function should only be used as part of the series: SsBlockVoiceAllocation() -> SsAllocateVoices()-> 
SsSetVoiceSettings()-> SsQueueRegisters()-> SsQueueKeyOn()-> SsQueueReverb() -> 
SsUnBlockVoiceAllocation() 


Return value 
1 if successful; -1 if voice allocation system already blocked, by either a previous call to this function with 
no correspnding call to SsUnBlockVoiceAllocation() or a call to SsUtKeyOn(), SsUtKeyOnV() or a MIDI key 
on command. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsSetVoiceSettings(), 
SsQueueRegisters(), SsQueueKeyOn(), SsQueueReverb(), SsUnBlockVoiceAllocation(), SsFindPitchd, 
SsGetActualProgFromProg(), SsVoiceCheck() 
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SsChannelMute 
Select MIDI channels for muting. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.6 12/14/98 
Syntax 
void SsChannelMute( 
short acn, SEP access number 
short trn, SEQ number within SEP 
(O when the music score data is SEQ) 
long channels) MIDI channel 
Explanation 


Selects MIDI channels that are muted. The low 16 bits of channels represent each channel; a bit set to 1 
means the voice should be muted. This function can be called when playing is in progress, or before 
playing has begun, to initiate muting. 


See also 
SsSeqPlay(), SsSepPlay() 
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SsEnd 


Stop the sound system. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
void SsEnd(voic) 


Explanation 


If SsSetTickMode() is used to set a mode that automatically calls SsSeqCalledTbyT(), this function stops 
SsSeqCalledTbyT() from being called at every tick. 


See also 
SsStart(), SsSetTickMode(), SsSeqCalledTbyT(), SsQuit() 
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SsGetActualProgFromProg 


Convert a program number into a “real” program or offset number. 


Library Header File Introduced Documentation Date 
libsnd. lib libsnd.h 4.1 12/14/98 
Syntax 
short SsGetActualProgFromProg( 
short vabid, VAB number containing desired tone information 
short ProgNum) Program number containing tone information 
Explanation 


Used to determine the “real” program number of tone information. This number is only incremented by valid 
programs (programs containing one or more tones) and so may differ from the program number. Example: 
In a VAB with valid programs 0-10 and 100-127, the prog_num of program 127 = 127, while the 
prog_actual of program 127 = 38. This number is used to calculate the offset of tone information in the 
VAB header. 


Return value 
The “real” program number upon success; -1 if vabld or ProgNum are out of range. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), SsSetVoiceSettings(), 
SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SsGetChannelMute 


Get muted channel number 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.0 12/14/98 

Syntax 

long SsGetChannelMute( 

short sep_num, SEQ/SEP access number 

short seq_num) SEQ number within SEP data 

Explanation 

Returns muted MIDI channels. 


Return value 
Bit field showing muted MIDI channels (1= muted; O = not muted). 


See also 
SsChannelMute() 
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SsGetCurrentPoint 

Get current position in SEQ/SEP data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.6 12/14/98 

Syntax 

u_char *SsGetCurrentPoint( 

short acn, SEP access number 

short trn) SEQ number within SEP 


(O when the music score data is SEQ) 


Explanation 
Obtains the address of the current position in the SEQ/SEP data that is being played. 


Return value 
SEP/SEQ data address. 


See also 
SsSeqPlay(), SsSepPlay() 
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SsGetMute 


Get mute attribute. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
char SsGetMute (voia) 


Explanation 
Obtains the mute attribute. 


Return value 
SS_MUTE_ON = Mute on; SS_MUTE_OFF = Mute off 


See also 
SsSetMute() 
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SsGetMVol 


Get main volume value. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
void SsGetMVol( 
SndVolume *m_vol) Pointer to main volume value 


Explanation 
Returns the main volume value to m_vol. 


See also 
SsSetMVol() 
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SsGetNck, SsSetNck, SsSetNoiseOff, SsSetNoiseOn 


Libsnd noise functions (Not supported) 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.1 12/14/98 

Syntax 

short SsGetNck(voic) Get noise clock value 

void SsSetNck( Set noise clock value 

short n_clock) Noise clock value (0 — Oxf) 

void SsSetNoiseOff(voia) Sets noise off 

void SsSetNoiseOn( Sets noise on 

short voll, L channel volume value 

short voir R channel volume value 

Explanation 


Libsnd noise functions. 


Note: These functions are not supported. Instead, use libspu noise functions or create a noise VAG from 
recorded AIFF. 
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SsGetRVol 


Get reverb volume value. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
void SsGetRVol( 
SndVolume *r_vol) Pointer to reverb volume value 


Explanation 
Returns the reverb volume value to r_vol. 


See also 
SsSetRVol() 
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SsGetSerialAttr 

Get value of a serial attribute. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

char SsGetSerialAttr( 

char s_num, Serial Number 

char attr) Attribute 

Explanation 





Returns the specified serial attribute value. 
s_num can be SS_SERIAL_A for Serial A (CD input), or SS_SERIAL_B for Serial B (external digital input). 
attr can be SS_MIX for mixing, or SS_REV for reverb. 


Return value 
1 if attribute is on, O if attribute is off. 


See also 
SsSetSerialAttr() 
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SsGetSerialVol 


Get a serial volume value. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.1 12/14/98 


Syntax 

void SsGetSerialVol( 

char s_num, Serial number 
SndVolume *s_vol Pointer to volume value 


Explanation 
Returns the specified serial volume value to s_vol. 


s_num can be SS_SERIAL_A for Serial A (CD input), or SS_SERIAL_B for Serial B (external digital input). 


See also 
SsSetSerialVol() 
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SsGetVoiceMask 

Get voices blocked from access by voice allocation system. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

u_long SsGetVoiceMask(voic) 

Explanation 

Returns a bit mask containing the voices that are blocked from access by the libsnd voice allocation 

system. 


Return value 


A value whose bits are set for each voice that is blocked. To find out if a specific voice is blocked, use the 
bit values SPU_xxCH(xx=0~298). 


See also 
SsSetVoiceMask(), SsSetReservedVoice() 
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Sslnit 


Initialize sound system. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
void Sslnit(void) 


Explanation 
Initializes the sound system, clearing the sound local memory. 


See also 
SsinitHot(), SsEnd(), Spulnit() (see libspu) 
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SsInitHot 

Initialize sound system (hot reset). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.1 12/14/98 

Syntax 


void SsinitHot(voic) 


Explanation 


Initializes the sound system, without destroying data that has been transferred to the sound buffer. Using 
Exec()-related functions, when a child process wants to initialize the sound system with the sound buffer in 
its current state, it should call SsInitHot() instead of calling Sslnit(). 


See also 
Sslnit), Exec() (See libapi), SpulnitHot() 
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SsIsEos 

Determine whether a song is being played. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SslsEos( 

short access_num, SEQ/SEP access number 

short seg_num) SEQ number inside SEP data 

Explanation 


Determines whether or not a specified song is being played. 





When using this function for SEQ data, set seq_num to O; for SEP data, set it to the number of the SEQ to 
be played. 


Return value 
1 if the song is being played; O if the song is not being played. 
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SsPitchFromNote 
Convert MIDI note information into a pitch playback rate. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 
Syntax 
u_short SsPitchFromNote( 
short note, MIDI note number (0-127) at which the tone is keyed on. 
short fine, The fine-tuning adjustment in cents, of note. Values range from 0-127, 
but are scaled to cents. 
u_char center, MIDI note number (0-127) at which the tone was created; the center 
member of the VagAtr structure. 
u_char shift) The fine-tuning adjustment in cents, of center; the shift member of the 


VagAtr structure. Values range from 0-127, but are scaled to cents. 


Explanation 
Calculates a pitch value to be applied to a voice in the function SsQueueRegisters\(). 


Return value 
The calculated pitch value. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SsPlayBack 

Restarts currently playing seq/sep data at beginning 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsPlayBack( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number inside SEP data 

short /_count) Song repetition count 

Explanation 


Stops the song being played, returns to the start of the song, and begins playing it again. 


When using this function for SEQ data, set seq_num to 0. When using this function for SEP data, set the 
number that contains the SEQ to be played. 


Specify a song repetition count in /_count. For infinite play repetition, specify SSPLAY_INFINITY. 


See also 
SsSeqPlay(), SsSepPlay() 
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SsQueueKeyOn 

Set voices in key on queue to be processed at next tick callback. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

void SsQueueKeyOn( 

long voices) Bit field containing voices to be set in the key on queue 

Explanation 


Hooks into the key on system of libsnd. 


Set the individual bits of voices using the values SPU_xxCH(0-23) for the desired voices to be set in the key 
on queue. 





This function should only be used as part of the series SsBlockVoiceAllocation() -> SsAllocateVoices()-> 
SsSetVoiceSettings()-> SsQueueRegisters()-> SsQueueKeyOn()-> SsQueueReverb() -> 
SsUnBlockVoiceAllocation(). 


See also 


SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueRegisters(), SsQueueReverb(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SsQueueRegisters 

Place values in register queue to be set at next tick callback. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

void SsQueueRegisters( 

long voice, The voice number for which the SPU registers need to be set (0-23) 

SndRegisterAttr *SRA) Values to be sent to the SPU registers 

Explanation 


Queues the SndRegisterAttr to be processed at the next tick callback. 
SRA members are as follows: 


volume.left and volume.right: Any value between -0x4000 ~ OxSfff. This is equivalent to volume mode 
SPU_VOICE_DIRECT (See SpuSetVoiceAttr() for details). Normally, libsnd takes only values from 0-127 
and converts them to short int via the algorithm listed in the overview of libsnd. The volume calculations 
may be emulated or an algorithm to use fewer CPU cycles or do 3-D sound volume calculations may 
be substituted. 

pitch: When using this function in the libsnd emulation functions series, the value set in pitch must 
match the value of the pitch member of the SndVoiceStats structure set in SsSetVoiceSettings(). When 
using this function to change pitch when the voice is currently sounding, SsPitchFromNote() may be 
used to calculate the pitch, or a user-defined pitch lookup table may be used. 


mask: may be set by ORing the desired following list of attributes (if mask is set to O, all attributes are 








set): 

Table 14-2 
Attribute Description 
SND_VOLL left volume 
SND_VOLR right volume 
SND_PITCH pitch 
SND_ADDR waveform data start address 
SND_ADSR1 adsr1 information 
SND_ADSR2 adsr2 information 





addr: Contains the waveform data start address. May be obtained using SsUtGetVagAddrFromTone(). 


adsr1: Contains adsr information for the voice. Should initially be set to the adsr1 member of VagAtr 
for the tone assigned to the voice. 
adsr2: Contains adsr information for the voice. Should initially be set to the adsr2 member of VagAtr 
for the tone assigned to the voice. 








This function must be used in the series: SsBlockVoiceAllocation() -> SsAllocateVoices() -> 
SsSetVoiceSettings() -> SsQueueRegisters()-> SsQueueKeyOn() -> SsQueueReverb() -> 
SsUnBlockVoiceAllocation() when keying sounds on via the libsnd emulation method. 


It may also be called at any time after the sound has been keyed on to change any of the members of 
SndRegisterAttr, provided that the function SsVoiceCheck() is called first to ensure voice integrity. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueReverb(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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14-36 Extended Sound Library Functions 








SsQueueReverb 

Set voices in reverb queue to be processed at next tick callback. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

void SsQueueReverb( 

long voices, Bitfield containing voices for which reverb will be changed 

long reverb) Bitfield containing reverb on/off data to be set in the reverb queue 

Explanation 





Hooks into the reverb queueing systems of libsnd, for applying reverb to sounds about to key on, altering 
the reverb of currently playing sounds, or applying reverb for libspu voices when both sound libraries are 
used together. 


Set the arguments as follows: 





voices OR SPU_xxCH(0-28) for the desired 
voices to be set in the reverb queue. 
reverb Reverb queue bitfield. 
Reverb is affected for all high bits of 
voices. 


If bit = O Reverb is turned off for that voice 
If bit = 1 Reverb is turned on for that voice 


If this function is being used as part of the libsnd key-on emulation series: 


SsBlockVoiceAllocation() -> SsAllocateVoices() -> SsSetVoiceSettings() -> SsQueueRegisters() -> 
SsQueueKeyOn() -> SsQueueReverb() -> SsUnBlockVoiceAllocation(), the mode member of the VagAtr for 
the voice may be checked to determine whether reverb should affect that voice. 





This function may also be used as a workaround for the reverb conflict between libspu and libsnd. Voices 
being used by libspu may have reverb changed using this function. 


Also, this function is an ideal solution to changing reverb mode during playback of sound. In libsnd it is 
currently difficult to change reverb mode during playback of sound effects or MIDI music. 


See also 


SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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SsQuit 


Terminate the sound system. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 
void SsQuit(voia) 


Explanation 


Terminates the sound system; transfer to the sound buffer is disabled. To re-enable transfer to the sound 
buffer, call Sslnit(). 


SsEnd() must be called before SsQuit(). 


See also 
SsEnd(), SsStart(), SsSetTickMode(), SsSeqCalledTbyT() 


CONFIDENTIAL Run-Time Library Reference 


14-38 Extended Sound Library Functions 


SsSepClose 
Close SEP data. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepClose( 

short sep_access_num) | SEP access number 

Explanation 

Closes SEP data with sep_access_num that is no longer needed. 





All SEQ data stored in the closed SEP becomes inaccessible. Before executing this function, use 
SsSepStop() with the applicable SEP. 


See also 
SsSepOpen() 
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SsSepOpen 

Open SEP data. 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 

Syntax 

short SsSepOpen( 

u_long “adar, Pointer to starting address of SEP data within the main memory 

short vab_id, VAB id 

short seg_num) Number of SEQs contained in SEP 

Explanation 


Analyzes the SEP data located in the main memory, and returns a SEP access number. Up to 32 pieces of 
SEP data can be opened simultaneously when combined with the number of open SEQ data. 


For Library Versions 4.0 and earlier: 


1) Do not call this from inside a callback; 
2) If your s_max from SsSetTableSize() is less than 32, you must keep track of your open SEQs/SEPs so 
as not to exceed the limit set by s_max. 





Return value 


SEP access number: an internal SEP data management table number that has the same characteristics as 
the SEQ access number. 





See also 
SsSepClose() 
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SsSepOpenJ 

Open SEP data (function table version). 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.6 12/14/98 

Syntax 

short SsSepOpenJ( 

u_long “adar, Pointer to starting address of SEP data within the main memory 

short vab_id, VAB id 

short seg_num) Number of SEQs contained in SEP 

Explanation 


Equivalent to SsSepOpen)\) if all the low-level MIDI functions were registered. In addition to the SsSepOpen() 
capability, this function enables a programmer to control functions to be registered to the table and thus 
improve code efficiency by not calling unnecessary low-level functions. 





Failure to properly register all necessary low-level MIDI functions will result in a bus error. 


Before calling this function, you must have confirmed with SsVabTransCompleted() that the VAB data from 
the vab_id has completed being transferred to the sound buffer. 


For Library Versions 4.0 and earlier: 


1) Do not call this from inside a callback; 
2) If your S_max from SsSetTableSize() is less than 32, you must keep track of your open SEQs/SEPs so 
as not to exceed the limit set by s_max. 








Return value 


SEQ Access Number: Used in the SEQ data access function, being the inner SEQ data control table 
number. 


See also 
SsSepOpen(), _SsFCALL(), dmy_Ss...() 
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SsSepPause 

Pause the reading of SEP data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 


void SsSepPause( 
short sep_access_num, | SEP access number 
short seq_num) SEQ number inside SEP data 


Explanation 
Pauses the reading (playing) of the seq_num SEQ data of SEP data possessing sep_access_num. 


See also 
SsSepReplay() 
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SsSepPlay 
Read (play) SEP data. 


Library 
liosnd.lib 


Syntax 

void SsSepPlay( 

short seo_access_num, 
short seg_num, 

char play_mode, 

short /_count) 


Explanation 


Header File Introduced Documentation Date 


libsnd.h 3.0 12/14/98 


SEP access number 
SEP data SEQ number 
Play mode 

Song repetition count 


Begins to read (play) SEQ data specified by the SEP data seq_num specified by seq_access_num, if 
play_mode = SSPLAY_PLAY. If play mode = SSPLAY_PAUSE, makes a pause state. For infinite play 
repetition, specify SSPLAY_INFINITY in /_count. 





sepl = SsSepOpen (addr, vab_id, 4); /* Open SEP data containing four pieces 








SsSepPlay (sepl, 2, SSPLAY_PLAY, 2); /* Immediately play 3rd SI 








EP data twice */ 


Example: 
of SEQ data */ 
opened SI 

See also 

SsSepStop() 


Run-Time Library Reference 


CONFIDENTIAL 


EQ data of 





Extended Sound Library Functions 14-43 


SsSepReplay 

Resume (replay) reading SEP data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 


void SsSepReplay( 

short sep_access_num, | SEP access number 

short seq_num) SEQ number inside SEP data 
Explanation 


Resumes reading the seq_num-th SEQ data of SEP data with sep_access_num, that was paused by 
SsSepPause(). 


See also 
SsSepPause() 
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SsSepSetAccelerando 

Accelerate the tempo. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepSetAccelerando( 

short sep_access_num, SEP access number 

short seg_num, SEQ number inside SEP data 

long tempo, Desired song tempo 

long v_time) Time (in ticks) 

Explanation 

Increases the tempo of the seq_num-th SEQ data of SEP data with sep_access_num up to tempo within 

v_time. 


If tempo is smaller (slower) than the current tempo, this function acts the same as SsSepSetRitardando(). 


See also 
SsSepSetRitardando() 
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SsSepSetCrescendo 

Crescendo (valid for individual SEQ in SEP). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepSetCrescendo( 

short sep_access_num, SEP access number 

short seg_num, SEQ number inside SEP data 

short vol, Volume value (0-127) 

long v_time) Time (in tick units) 

Explanation 


Raises the main volume of the seq_num-th SEQ data of SEP data with sep_access_num by vol within 
v_time (or to the maximum value). It has no effect if the volume of each voice is at the maximum or if vol is a 
negative number. It is recommended that v_time be set to an integer multiple of vol. 


See also 
SsSepSetDecrescendo() 
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SsSepSetDecrescendo 

Decrescendo (valid for individual SEQ in SEP). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepSetDecrescendo( 

short sep_access_num, SEP access number 

short seg_num, Number inside SEP data 

short vol, Volume value (0-127) 

long v_time) Time (in tick units) 

Explanation 


Lowers the main volume of the seq_num-th SEQ data of SEP data with seo_access_num by vol within 
v_time (or to the minimum value). This function has no effect if the volume of each voice is at the minimum 
or if vol is a negative number. It is recommended that v_time be set to an integer multiple of vo/. 


See also 
SsSepSetCrescendo() 
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SsSepSetRitardando 

Slow the tempo. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepSetRitardando( 

short sep_access_num, SEP access number 

short seg_num, SEQ number inside SEP data 

long tempo, Desired song tempo 

long v_time) Time (in tick units) 

Explanation 


Slows the tempo of the seq_num SEQ data of SEP data possessing sep_access_num down to tempo 
within v_time. If tempo is larger (faster) than the current tempo, this function acts the same as 
SsSepSetAccelerando(). 


See also 
SsSepSetAccelerando() 
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SsSepSetVol 

Set SEP volume (valid for individual SEQ in SEP). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSepSetVol( 

short sep_access_num, | SEP access number 

short seg_num, SEQ number inside SEP data 

short voll, L channel main volume value 

short voir) R channel main volume value 

Explanation 


Sets the L and R channels for the main volume of the seq_num-th SEQ data of SEP data with 
sep_access_num to specified values (between O and 127). 
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SsSepStop 
Stop reading SEP data. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 
Syntax 


void SsSepStop( 
short sep_access_num, SEP access number 
short seq_num) SEQ number inside SEP data 


Explanation 
Stops reading (playing) the seq_num-th SEQ data of SEP data with seo_access_num. 


See also 
SsSepPlay() 
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SsSeqCalledTbyT 

Interpret SEQ/SEP data and carry out playback. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSeqCalledTbyT(voia) 

Explanation 


At each Tick this function is called; it interorets SEQ/SEP data and carries out playback. The tick rate is set 
by SsSetTickMode(), but this merely regulates the internal sound system, without depending either on the 
speed or resolution determined by SEQ/SEP data. 


When SsSetTickMode() is called with tick_mode SS_NOTICK, this function must be called by the program 
(usually with vertical sync timing). Otherwise, the sound processing code automatically calls this function at 
the given resolution. 


See also 
SsSetTickMode() 
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Extended Sound Library Functions 14-51 


SsSeqClose 
Close SEQ data. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 


void SsSeqClose( 
short seg_access_num) SEQ access number 


Explanation 
Closes SEQ data with an un-needed seq_access_num. 


Before executing this function, use SsSeqStop() with the applicable SEQ. 


See also 
SsSeqOpen() 
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14-52 Extended Sound Library Functions 


SsSeqGetVol 

Get SEQ volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSeqGetVol( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number of SEP data 

short *voll, L volume of SEQ data 

short *volr) R volume of SEQ data 

Explanation 


Returns current left and right SEQ volume to voll and volr. Set seq_num at O for SEQ data, and set it at 
appropriate SEQ number for SEP data. The volume value set by SsSepSetVol() can be obtained. 


See also 
SsSeqSetVol(), SsSepSetVol() 
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Extended Sound Library Functions 14-53 


SsSeqOpen 
Open SEQ data. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 

short SsSeqOpen( 

u_long *adar, Pointer to start address of SEQ data in the main storage 
short vab_ic) VAB id 


Explanation 
Designates an SEQ number for the SEQ data to allow playback. 


Before calling this function, you must have confirmed with SsVabTransCompleted() that the VAB data from 
the vab_id has completed being transferred to the sound buffer. 


For Library Versions 4.0 and earlier: 
1) Do not call this function from inside a callback; 


2) If your s_max from SsSetTableSize() is less than 32, you must keep track of your open SEQs/SEPs so as 
not to exceed the limit set by s_max. 





Return value 
SEQ access number. This value is passed to other SEQ routines such as SsSeqPlay(). 





If you try to open more than 32 SEP data (combined with SEQ data) at the same time, -1 is returned. 


See also 
SsSeqClose() 
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14-54 Extended Sound Library Functions 


SsSeqOpenJ 

Open SEQ data (function table version). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.6 12/14/98 

Syntax 

short SsSeqOpenJ( 

u_long “addr, Pointer to start address of SEQ data in the main storage 

short vab_ic) VAB id 

Explanation 


Equivalent to SsSeqOpen(\ if all the low-level functions were registered. In addition to the SsSeqOpen() 
capability, this function enables a programmer to control functions to be registered to the table and thus 
improve code efficiency by not calling unnecessary low-level functions. 





Failure to properly register all necessary low-level MIDI functions will result in a bus error. 


Before calling this function, you must have confirmed with SsVabTransCompleted() that the VAB data from 
the vab_id has completed being transferred to the sound buffer. 


For Library Versions 4.0 and earlier: 


1) Do not call this from inside a callback; 
2) If your s_max from SsSetTableSize() is less than 32, you must keep track of your open SEQs/SEPs so 
as not to exceed the limit set by s_max. 








Return value 
SEQ access number. This value is passed to other SEQ routines such as SsSeqPlay(). 


See also 
SsSeqOpen() 
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Extended Sound Library Functions 14-55 


SsSeqPause 

Pause SEQ data reading. 
Library Header File Introduced Documentation Date 
libsnd. lib libsnd.h 3.0 12/14/98 

Syntax 


void SsSeqPause( 
short seg_access_num) SEQ access number 


Explanation 
Stops reading (playing) SEQ data with seq_access_num. 


See also 
SsSeqReplay() 
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14-56 Extended Sound Library Functions 


SsSeqPlay 

Read (play) SEQ data. 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 

Syntax 

void SsSeqPlay( 

short seg_access_num, | SEQ access number 

char play_mode, Performance mode 

short /_count) Number of repeats of the music 

Explanation 


Selects either immediate SEQ data reading (play_mode = SSPLAY_PLAY) or sets a pause state at the start 
of SEQ data (play_mode = SSPLAY_PAUSE). Specify the number of times to repeat the music by /_count, 
using SSPLAY_INFINITY for unlimited play. 


See also 
SsSeqPause() 
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Extended Sound Library Functions 14-57 


SsSeqPlayPtoP 

Read SEQ data (play interval). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.2 12/14/98 

Syntax 

void SsSeqPlayPtoP( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number within SEP (0 if music data is SEQ) 

u_char *start_point, Load (play) start point 

u_char *end_point, Load (play) end point 

char play_mode, Performance mode 

short /_count) Loop count 

Explanation 





Loads (plays) the data interval specified by start_point and end_point. These values are obtained from 
SsGetCurrentPoint(). 


If play_mode = SSPLAY_PLAY, SEQ data is read (played) immediately. If olay_mode = SSPLAY_PAUSE, a 
pause is entered at the start of the SEQ data (the start of the song). 


|_count specifies the number of times the song is to be looped. Use SSPLAY_INFINITY for an infinite loop. 


See also 
SsSeqPlay(), SsSepPlay(), SsGetCurrentPoint() 
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14-58 Extended Sound Library Functions 


SsSeqReplay 

Resume SEQ data reading (Replay) . 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 


void SsSeqReplay( 
short seg_access_num) | SEQ access number 


Explanation 
Resumes reading SEQ data with seq_access_num stopped by SsSeqPause(). 


See also 
SsSeqPause() 
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Extended Sound Library Functions 14-59 


SsSeqSetAccelerando 
Quicken tempo. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 

void SsSeqSetAccelerando( 

short seg_access_num, SEQ access number 
long tempo, Desired music tempo 
long v_time) Time (in ticks) 
Explanation 


Quickens the SEQ data with seq_access_num to the tempo resolution in v_time. If the specified resolution 
is smaller (slower) than the current resolution, the effect is the same as SsSeqSetRitardando(). 


See also 
SsSeqSetRitardando() 
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14-60 Extended Sound Library Functions 


SsSeqSetCrescendo 

Crescendo. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSeqSetCrescendo( 

short seg_access_num, SEQ access number 

short vol, Volume value (0-127) 

long v_time) Time (in ticks) 

Explanation 


Increases the main volume of SEQ data with seq_access_num by the vol value in v_time. If the voice 
volume is at the maximum (127), or if vol is a negative number, the function has no effect. It is 
recommended that v_time be set to an integer multiple of vol. 


See also 
SsSeqSetDecrescendo() 
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Extended Sound Library Functions 14-61 


SsSeqSetDecrescendo 

Decrescendo. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSeqSetDecrescendo( 

short seg_access_num, SEQ access number 

short vol, Volume value (0-127) 

long v_time) Time (in ticks) 

Explanation 


Lowers main volume of SEQ data with seq_access_num by the vol value in v_time. If each voice volume is 
the minimum value (0), or if vol is a negative number, there is no effect. It is recommended that v_time be 
set to an integer multiple of vol. 


See also 
SsSeqSetCrescendo() 
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14-62 Extended Sound Library Functions 


SsSeqSetNext 

Specify SEQ data to play next after a given SEQ. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSeqSetNext( 

short seg_access_num1, SEQ access number 

short seg_access_num2) SEQ access number of next SEQ to play 

Explanation 


Specifies that whenever SEQ data represented by seq_access_num1 plays, the SEQ data represented by 
seq_access_num2 should play next. 


See also 
SsSetNext() 
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Extended Sound Library Functions 14-63 


SsSeqSetRitardando 


Slow tempo. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 

Syntax 

void SsSeqSetRitardando( 

short seg_access_num, SEQ access number 

long tempo, Desired music tempo 

long v_time) Time (in ticks) 

Explanation 


Slows the SEQ data with seq_access_num to the tempo resolution in v_time. If the specified resolution is 
larger (faster) than the current resolution, the function is the same as SsSeqSetAccelerando(). 


See also 
SsSeqSetAccelerando() 
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14-64 Extended Sound Library Functions 


SsSeqSetVol 

Set SEQ volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 


void SsSeqSetVol( 
short seg_access_num, | SEQ access number 


short voll, Left channel’s main volume value 
short voir) Right channel’s main volume value 
Explanation 


Sets the main volume of music with seq_access_num to values specified for voll and volr (from O to 127). 
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Extended Sound Library Functions 


SsSeqSkip 

Skip SEQ data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.2 12/14/98 

Syntax 

int SsSeqSkip( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number within SEP (0 if music data is SEQ) 

char unit, Skip unit 

short count) Skip amount 


Explanation 


Moves the playback pointer of the song data represented by access_num and seq_num forward count 


times, in units specified by unit. 


Table 14-3 





Unit 


Skip unit 





SSSKIP_TICK 
SSSKIP_NOTE4 
SSSKIP_NOTE8 
SSSKIP_BAR 


TICK unit 

Quarter note unit 
One-eighth note unit 
Measure unit 





Return value 


O if the function was successful; -1 if the operation failed 
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14-65 


14-66 Extended Sound Library Functions 


SsSeqStop 

Terminate SEQ data reading. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

void SsSeqStop( 


short seg_access_num) SEQ access number 


Explanation 
Terminates playing of the SEQ data with seq_access_num. 


See also 
SsSeqPlay() 


Run-Time Library Reference CONFIDENTIAL 





Extended Sound Library Functions 14-67 


SsSetAutoKeyOffMode 

Set automatic KeyOff mode. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSetAutoKeyOffMode( 

short mode) 0: Automatically keys off 


7: Does not key off until a KeyOff request comes in 





Explanation 


Sets the automatic KeyOff mode. The default is the automatic KeyOff mode. If the envelopes for a specific 
voice for the past 16 interrupts contain all O's, the automatic KeyOff mode assumes that waveform 
playback has been automatically terminated, and uses the voice for other waveform playback. 
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14-68 Extended Sound Library Functions 


SsSetCurrentPoint 

Set data address in SEQ/SEP. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.2 12/14/98 

Syntax 

int SsSetCurrentPoint( 

short acn, SEP access number 

short trn, SEQ number within SEP (0 if music data is SEQ) 

u_char *point) SEQ/SEP data address 

Explanation 


Sets the data address obtained from SsGetCurrentPoint() in SEQ/SEP. 


Return value 
O if the function was successful 


-1 if the operation failed 


See also 
SsGetCurrentPoint() 
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Extended Sound Library Functions 14-69 


SsSetLoop 

Set song repetition count. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSetLoop( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number inside SEP data 

short /_count) Song repetition count 

Explanation 


Sets a song repetition count. This function is useful for changing the song repetition count set in 
SsSeqPlay. After this function is called, the current song repetition count is reset, and the song is played for 
the number of times set by the new count. 





When using this function for SEQ data, set O in seq_num; when using this function for SEP data, set the 
number that contains the SEQ to be played. 
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14-70 Extended Sound Library Functions 


SsSetMarkCallback 

Register a function to be called when a mark is detected. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

typedef void 


(*SsSeqMarkCallbackProc) 
(short, short, short); 


void SsSetMarkCallback( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number inside SEP data 

SsMarkCallbackProc proc) Callback function to be called when Mark is detected 


Explanation 

proc specifies a callback function to be called when a mark is detected inside a song identified by 
access_num. |f proc is O, any previous callback is cleared. Only one callback function can be registered at 
a time.The arguments passed to the callback function are, in order: 


e = SEQ/SEP number 
e SEQ number inside SEP data (O when using SEQ) 
e The data2 value following the callback marker in the song data is passed to the third argument. 


Sample: 


/* Callback function-definition*/ 
SsMarkCallbackProc proc (short ac_no, short tr_no, short 
data); 


/* Opens SEQ */ 

short seq_a_num = SsSeqOpen (addr, vab_id); 

/* Sets Callback function */ 

SsSetMarkCallback (seq_a_num, 0, (SsMarkCallbackProc) proc); 
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Extended Sound Library Functions 14-71 


SsSetMono 


Set monaural mode. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 
void SsSetMono(voia) 


Explanation 


Sets the output to monaural mode. Forces all libsnd keyed-on voices to have equivalent left and right 
volumes. Stereo mode is the system default mode. 


See also 
SsSetStereo() 
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14-72 Extended Sound Library Functions 


SsSetMute 
Sets Muting. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 

void SsSetMute( 

char mode) Setting mode 

Explanation 

If mode is SS_MUTE_ON, the sound system is muted. If mode is SS_MUTE_OFF, the sound system is 
unmuted. 
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Extended Sound Library Functions 14-73 


SsSetMVol 


Set main volume value. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 

void SsSetMVol( 

short voll, L channel volume value 
short voir) R channel volume value 


Explanation 
Sets the master volume for the sound system to voll and volr (values range from O to 127). 


You must call this function before playing sequence (SEQ, SEP) data. 


See also 
SsGetMVol() 
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14-74 Extended Sound Library Functions 


SsSetNext 
Set the next SEQ/SEP data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.2 12/14/98 
Syntax 
void SsSetNext( 
short ac_no7, SEP/SEQ access number 
short tr_no7, SEQ number in SEP (If the score data is SEQ, tr_no1 is 0.) 
short ac_no2, SEP/SEQ access number 
short tr_no2) SEQ number in SEP (If the score data is SEQ, tr_no2 is 0.) 
Explanation 


Sets the score data with SEP/SEQ access numbers (ac_no2, tr_no2) to be played after SEP/SEQ data 
(ac_no7, tr_no7). 


The next score data is played automatically after the previous score finishes playing. 


See also 
SsSeqSetNext() 
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Extended Sound Library Functions 14-75 


SsSetReservedVoice 

Declare the number of voices to be allocated by libsnd. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

char SsSetReservedVoice( 

char voices) Voice count 

Explanation 


Declares the number of voices that the libsnd voice allocation management system has access to. Other 
voices can be keyed on in libspu or via SsUtKeyOnvV(). 


Voice numbers are reserved from the lower end (from 0). For example, if voices = 20, then: 





e Voices 0-19 are used for allocation by lilbsnd. 
e Voices 20-23 are available for libspu. 


Should only be called once, before start of sound processing (SsStart/SsStart2()). 


Return value 
Returns the set voice count if successful. Returns -1 if unsuccessful. 
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14-76 Extended Sound Library Functions 


SsSetRVol 


Set reverb volume values. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 

void SsSetRVol( 

short voll, L channel’s volume value 

short voir) R channel’s volume value 

Explanation 

Sets the reverb volume for left and right channels. The value ranges from 0 to 127. 





See also 
SsGetRVol() 
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Extended Sound Library Functions 14-77 


SsSetSerialAttr 

Set a serial attribute. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

void SsSetSerialAttr( 

char s_num, Serial number 

char attr, Attribute value 

char mode) Setting mode 

Explanation 


Sets a serial attribute. 


e s num: SS_SERIAL_A = Serial A (CD input). SS_SERIAL_B = Serial input line B (external digital input) 
e attr: SS_MIX = Mixing. SS_REV = Reverb 
e mode: SS_SON = attr on. SS_SOFF = attr off 


See also 
SsGetSerialAttr() 
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14-78 Extended Sound Library Functions 


SsSetSerialVol 

Set serial volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

void SsSetSerialVol( 

char s_num, Serial number 

short voll, L channel volume value 

short voir) R channel volume value 

Explanation 


Sets the serial volume in voll, volr. The volume values may be between 0-127. 
s_num: SS_SERIAL_A = Serial A (CD input). SS_SERIAL_B = Serial input line B (external digital input) 


See also 
SsGetSerialVol() 
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Extended Sound Library Functions 14-79 


SsSetStereo 

Set stereo mode. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 


void SsSetStereo(void) 


Explanation 
Sets the output to stereo mode. The sound system default output is stereo. 


See also 
SsSetMono() 
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14-80 Extended Sound Library Functions 


SsSetTableSize 

Specify the area of a SEQ/SEP data attribute table. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSetTableSize( 

char “table, Pointer to SEQ/SEP data attribute table area variable 

short s_max, Maximum times to open SEQ/SEP data (up to 32) 

short t_max) Number of SEQ included in SEP 

Explanation 


Specifies the area of a SEQ/SEP data attribute table. The library uses this area to analyze SEQ/SEP data, 
then saves it and plays it back. 


S_max specifies the maximum number of times SEQ/SEP data may be opened. The upper limit is 32. Once 
S_max is reached, unused SEQ/SEP data must be closed with SsSeqClose()/SsSepClose() before more 
data can be opened. t_max specifies the number of SEQ included in the largest SEP data. Set t_max to 1 
to handle only SEQ data and not use SEP data. The upper limit of t_max is 16. 





You must preserve the area for the table by using global variables or functions like malloc() (auto variables 
cannot be used). 





Use the following to find the size: 
(SS_SEQ_TABSIZ x s_max x t_max) 


where the constant SS_SEQ_TABSIZ is declared in 1ibsnd.h. (note that its value may vary from version to 
version). 


SsSetTableSize() should be called immediately after Sslnit(). Both functions should be called only once; 
what happens when multiple calls are made is unclear. 





See also 
Sslnit(), SslnitHot(), SsSeqOpen(), SsSepOpen() 
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Extended Sound Library Functions 14-81 


SsSetTempo 

Set a tempo. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsSetTempo( 

short access_num, SEQ/SEP access number 

short seg_num, SEQ number inside SEP data 

short tempo) Song tempo 

Explanation 


Sets a tempo. This function is useful for changing the tempo set in SsSeqPlay(). 


After this function is called, the current tempo is changed to the new tempo specified for playing songs. 





When using this function for SEQ data, set O in seq_num; when using this function for SEP data, set the 
number that contains the SEQ to be played. 
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14-82 Extended Sound Library Functions 


SsSetTickCallback 

Set the TickCallBack function called with every TICK. 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 

Syntax 

int SsSetTickCallback( 

void (*cb)()) Pointer to TickCallBack function called with every Tick 

Explanation 


Defines cb as the TickCallBack function called every tick. It is called only when SS_NOTICK has not been 
set by SsSetTickMode(), after SsStart() or SsStart2() have been called. 


When this function isn’t used to set the TickCallBack function, the default is SsSeqCalledTbyT\(). 


Return value 
Previously-set TickCallback function. 


See also 
SsSetTickMode(), SsStart(), SsStart2(), SsSeqCalledTbyT() 
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Extended Sound Library Functions 14-83 


SsSetTickMode 


Set tick mode. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 

void SsSetTickMode( 

long tick_mode) Tick mode (see table for values) 

Explanation 

Sets the resolution of a tick. Call this function only once before calling SsSeqOpen(), SsSepOpen() or 
SsStart() for the first time. When it is called multiple times, correct operation cannot be guaranteed. 


The tick mode does not depend on the speed or resolution specified by SEQ/SEP data, and merely 
specifies the resolution inside the sound system. 


The effects of SS_TICK50, SS_TICK60, and SS_TICKVSYNC differ according to the specification of 
SetVideoMode\() (see the individual entries below). 





tick_mode may be specified with the following values: 








Table 14-4 
tick_mode Tick setting: SEQ file played at 
SS_TICK50 1/50 second 
SS_TICK60 1/60 second 
SS_TICKVSYNC VSync Resolution (1/50 PAL, 1/60 NTSC) 
SS_TICK120 1/120 second 
SS_TICK240 1/240 second 
SS_NOTICK 1/60 second* 
Any resolution (60-240) 1/tick_mode seconds 
Any resolution | SS_NOTICK 1/tick_mode seconds* 








* SsSeqCalledTbyT() is called automatically every tick, except when tick_mode is SS_NOTICK or (any 
resolution | SS_NOTICkK). In those cases, the program must call SsSeqCalledTbyT() at the specified timing. 


“Any resolution” means that you specify a value between 60-240, and the resolution is 1/tick_mode. 
Example: tick_mode = 65 | SS_NOTICK sets up a resolution of 1/65th second. 


The OS Root Counter RCntCNTS is used to generate VSYNC timing. Therefore, if you use SS_TICK50 
with MODE_PAL (specified in SetVideoMode()), or SS_TICK6O with MODE_NTSC, or SS_TICKVSYNC, you 
shouldn't use RCntCNTS for any other timing resolution. 


The OS Root Counter RCntCNT2 is used for all other tick modes. Therefore, you shouldn’t use RCntCNT2 
for any other timing resolution. 





See also 
SsStart(), SsSeqCalledTbyT(), SetVideoMode() (See libete), SsSetTickCallback() 
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14-84 Extended Sound Library Functions 


SsSetVoiceMask 

Block voice allocation system from using the specified voices. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

void SsSetVoiceMask( 

u_long s_voice) voices that liosnd allocation system will not have access to. Specify the 


voices with the bits SPU_OCH..SPU_23CH. 


Explanation 

Blocks the voices specified in the bit mask s_voice from being accessed by the libsnd voice allocation 
system. These voices are then available for use via liospu calls or SsUtKeyOnvV() calls. This function differs 
from SsSetReservedVoice() in that a non-contiguous block of voices may be specified. For example, 
SsSetVoiceMask(6) gives the libsnd voice allocation system access to 22 voices - voices 0 and 3-28, while 
SsSetReservedVoice(22) gives it access to voices 0-21. The two functions may be used together, so that 
individual voices within the limits set by SsSetReservedVoice() may be blocked, but an easier method is to 
make one call to SsSetVoiceMask(). 





SsAllocateVoices() doesn’t include code to block these voices from the libsnd voice allocation system. 


See also 
SsGetVoiceMask(), SsSetReservedVoice() 
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Extended Sound Library Functions 





SsSetVoiceSettings 

Set internal liosnd variables for a voice. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

void SsSetVoiceSettings( 

long voice, Voice number (0-23) 

SndVoiceStats *Snd_v_attn Voice attributes to be set 

Explanation 


Hooks into the internal libsnd variables before key on of sound so that libsnd functions such as 
SsUtPitchBend() can be used to alter the voice after key on. 





The voice attributes Snd_v_attr must be set as follows: 


e  vagld: VAG number which tone to be keyed on points to. Can be obtained by using SsUtGetVagAtr(). 

e — vablid: VAB in which information for tone to be keyed on resides. 

e pitch: Original playback rate of tone. May be obtained by using SsFindPitch() or by creating a user- 
defined pitch lookup table. 

e vol: Maximum volume at which tone will be played back. Choose the greater value between left and 
right channel. Negative values are not valid (vol is invalid when used with 3D sound), and values range 
from 0-127. 

e pan: Relative pan value at which tone will be keyed on at. Not valid with 3D sound. Use the formula 
pan = volr * 64/ voll if volr>voll and pan = max volume (either OxSff or 127) - voll * 64/ volr if voll>volr. If 
voll = volr, pan = 64. 

e note: Note at which tone will be keyed on. 

e tone: Tone number to be keyed on. Determined by comparing the desired note with the min and max 
members of VagAtr for all tones within the specified program and vabid. 

e prog_num: The program number within which the tone information resides. 

e prog_actual: The “real” program number within which the tone information resides. The “real” number 
is only incremented by valid programs (programs containing one or more tones) and so may differ from 
the program number. Example: In a VAB with valid programs 0-10 and 100-127, the prog_num of 
program 127 = 127, while the prog_actual of program 127 = 38. This number is used to calculate the 
offset of tone information in the VAB header and may be obtained using SsGetActualProgFromProg)(). 

















This function should only be used as part of the series: SsBlockVoiceAllocation() -> SsAllocateVoices()-> 
SsSetVoiceSettings()-> SsQueueRegisters()-> SsQueueKeyOn()-> SsQueueReverb() -> 
SsUnBlockVoiceAllocation() 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), 
SsUnBlockVoiceAllocation(), SsVoiceCheck() 
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14-85 


14-86 Extended Sound Library Functions 


SsStart 

Start the sound system. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 


void SsStart(voia) 


Explanation 
Starts the sound system. 


When SsSetTickMode() is used to set a mode that calls SsSeqCalledTbyT() automatically, this function 
causes SsSeqCalledTbyT() to be called each tick. 


See also 
SsEnd(), SsSetTickMode(), SsSeqCalledTbyT() 
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Extended Sound Library Functions 14-87 


SsStart2 


Start the sound system (VSyncCallback version). 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.1 2/24/99 


Syntax 
void SsStart2(void) 


Explanation 
Starts the sound system. 


When SsSetTickMode() is used to set a mode that calls SsSeqCalledTbyT() automatically, this function 
causes SsSeqCalledTbyT() to be called each tick. 


SsStart2() must be used when the tick mode is equal to the TV’s sync rate (e.g. SS_TICK60 on NTSC or 
SS_TICK50 on PAL). In may also be used with other modes. 


See also 
SsStart(), SsEnd(), SsSetTickMode(), SsSeqCalledTbyT() 
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14-88 Extended Sound Library Functions 


SsUnBlockVoiceAllocation 


Release voice allocation system used by SsUtKeyOn(), SsUtKeyOnV(), and MIDI key on commands. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 4.1 12/14/98 
Syntax 


char SsUnBlockVoiceAllocation(void) 


Explanation 


Releases the voice allocation system used by SsUtKeyOn(), SsUtKeyOn(), SsAllocateVoices(), and MIDI key 
on commands. Must follow every call to SsBlockVoiceAllocation(). 





This function should only be used as part of the series: SsBlockVoiceAllocation() -> SsAllocateVoices()-> 
SsSetVoiceSettings()-> SsQueueRegisters()-> SsQueueKeyOn()-> SsQueueReverb() -> 
SsUnBlockVoiceAllocation(). 


Return value 
1 if successful; -1 if voice allocation system was not currently blocked. 


See also 

SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb\(), 
SsSetVoiceSettings(), SsVoiceCheck() 
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Extended Sound Library Functions 14-89 


SsUtAllKeyOff 


Key off all voices. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsUtAllKeyOff( 

short mode) Always O 

Explanation 


Keys off all voices used by the libsnd voice allocation system, as set by SsSetReservedVoice() and 
SsSetVoiceMask(). 
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14-90 Extended Sound Library Functions 


SsUtAutoPan 

Automatically change panning. 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.x 12/14/98 

Syntax 

short SsUtAutoPan( 

short vc, Voice number (0-23) 

short start_pan, Panning change start value (0-127) 

short end_pan, Panning change end value (0-127) 

short delta_time) Change time in ticks (0-10800) 

Explanation 


Linearly changes the panning from start_pan to end_pan at delta_time (in ticks) for voice vc. 


Return value 
O if successful; -1 if unsuccessful. 


See also 
SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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Extended Sound Library Functions 14-91 


SsUtAutoVol 

Automatically change voice volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtAutoVol( 

short vc, Voice number (0-23) 

short start_vol, Volume change start value (0-127) 

short end_vol, Volume change end value (0-127) 

short delta_time) Change time in ticks (O- 10800) 

Explanation 


Linearly changes the volume from start_vol to end_vol at delta_time (in ticks) for voice vc. 


Return value 
O if successful; -1 if unsuccessful. 


See also 
SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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14-92 Extended Sound Library Functions 


SsUtChangeADSR 

Change ADSR. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtChangeADSR( 

short vc, Voice number (0-23) 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

short prog, Program number (0-127) 

short o/d_note, Previous pitch specification in half-tone units (note number)(0-127) 

u_short adsr7, ADSR1 

u_short adsr2) ADSR2 

Explanation 


Changes the ADSR of the key on voice using SsUtKeyOn(). 


Return value 
O if successful; -1 if unsuccessful. 


See also 
SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn(), SsVabOpenHead)() 
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Extended Sound Library Functions 14-93 


SsUtChangePitch 
Change the pitch. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 
Syntax 
short SsUtChangePitch( 
short voice, Voice number (0-23) 
short vabld, VAB number (0-31) returned by SsVabOpenHead() 
short prog, Program number (0-127) 
short o/d_note, Previous pitch specification in semitones (note number) (0-127) 
short o/d_fine, Previous fine pitch specification (100/127 cents) (0-127) 
short new_note, New pitch specification in semitones (note number) (0-127) 
short new_fine) New fine pitch specification (100/127 cents) (0-127) 
Explanation 


Changes the pitch of the voice. 


Return value 
O if successful; -1 if unsuccessful. 


See also 
SsUtPitchBend(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 


CONFIDENTIAL Run-Time Library Reference 


14-94 Extended Sound Library Functions 


SsUtFlush 


Execute remaining queued KeyOn/KeyOff requests. 





Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 
void SsUtFlush(vo/c) 


Explanation 
Executes the remaining KeyOn/KeyOff requests that have been queued. 





Normally, flushing is performed by an automatic Sound Library interrupt (when the tick mode isn’t 
SS_NOTICKk) or by a clear call of SsSeqCalledTbyT (when the tick mode is SS_NOTICK). This function can 
also be used for flushing. It’s necessary to wait an interval of at least 1/44100 sec between consecutive 
calls to this function and/or SsSeqCalledTbyT(). 
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Extended Sound Library Functions 14-95 





SsUtGetDetVVol 

Get detailed value of voice volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtGetDetVVol( 

short vc, Voice number (0-23) 

short *detvoll, Pointer to detailed volume, left (O- 16383) 

short *detvolir) Pointer to detailed volume, right (O-16383) 

Explanation 


Returns the detailed value of the voice volume. 








Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtSetDetVVol(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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14-96 Extended Sound Library Functions 


SsUtGetProgAtr 

Get a program attribute table. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtGetProgAtr( 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

short progNum, Program number (0-127) 

ProgAtr “progatrptr) Pointer to program attribute table 

Explanation 


Specifies a VAB number and a program number, and returns the VAB attribute table to progatrptr. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtSetProgAtr(), ProgAtr() 
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Extended Sound Library Functions 14-97 


SsUtGetReverbType 


Get a reverb type. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short 

SsUtGetReverbType(voia) 

Explanation 

Obtains the current reverb type value. 


Return value 
Current reverb type value. 





See also 
SsUtSetReverbType(). 
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14-98 Extended Sound Library Functions 


SsUtGetVabHdr 
Get VAB attribute header. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtGetVabHdr( 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

ValbHdr *vabhdrptr) Pointer to VAB attribute header 

Explanation 

Returns the VAB attribute header to vabharptr of the VAB specified by vabid. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
VabHdr() 
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Extended Sound Library Functions 14-99 


SsUtGetVagAddr 

Get an SPU buffer address stored by VAG. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.1 12/14/98 

Syntax 

long SsUtGetVagAdadr( 

short vabld, VAB data id 

short vagla) VAG data id 

Explanation 


Given VAB id (0-15) and VAG id (1-254), this function returns a 32-bit SPU buffer address (as bytes) stored 
by VAG. 


Return value 
An SPU buffer address stored by VAG. 


See also 
SsVabOpenHead)() 
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14-100 Extended Sound Library Functions 


SsUtGetVagAddrFromTone 
Get SPU buffer address where VAG data is stored. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.3 12/14/98 

Syntax 

u_long SsUtGetVagAddrFromTone( 

short vabid, VAB id 

short progid, Program number 

short toneid) Tone number 

Explanation 


This function returns the address in the sound buffer where the VAG wave form data with the specified VAB 
id, program number, and tone number are transferred. 


Return value 
Address in the sound buffer. If it fails, it returns -1. 
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Extended Sound Library Functions 14-101 


SsUtGetVagAtr 

Get tone attribute table (VagAtr). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtGetVagAtr( 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

short progNum, Program number (0-127) 

short toneNum, Tone number (0-15) 

VagAtr *vagatrptr) Pointer to tone attribute table 

Explanation 


Specifies a VAB number, a program number, and a tone number, and returns a tone attribute table to 
vagatrpotr. 





Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtSetVagAtr(), VagAtr() 


CONFIDENTIAL Run-Time Library Reference 


14-102 Extended Sound Library Functions 


SsUtGetVBaddriInSB 

Get address in sound buffer to which VAB data has been transferred. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

u_long SsUtGetVBaddrInSB( 

short vabic) VAB id 

Explanation 

Returns the address inside the sound buffer to which the start of the VAB data specified by vabid has been 

transferred. 


Return value 
Address inside the sound buffer. Returns -1 if unsuccessful. 
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Extended Sound Library Functions 14-103 


SsUtGetVVol 

Get voice volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtGetVVol( 

short vc, Voice number (0-23) 

short *voll, Pointer to volume, left (0-127) 

short *volr) Pointer to volume, right (0-127) 

Explanation 


Returns a volume value for a voice. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtSetVVol(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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14-104 Extended Sound Library Functions 


SsUtKeyOff 
Key off voice. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 
Syntax 
short SsUtKeyOff( 
short voice, Voice number (0-23) access number 
short vabld, VAB number (0-31) returned by SsVabOpenHead)() 
short prog, Program number (0-127) 
short tone, Tone number (0-15) 
short note) Pitch specification in half-tone units (note number) (0-127) 
Explanation 


Keys off the voice. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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Extended Sound Library Functions 14-105 


SsUtKeyOffV 


Key off a voice. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 
short SsUtKeyOffV( 
short voice) Voice number (0-23) 


Explanation 
Keys off the voice specified by voice (0-23). 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtKeyOnvV() 
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14-106 Extended Sound Library Functions 





SsUtKeyOn 

Key on a voice. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsUtKeyOn( 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

short prog, Program number (0-127) 

short tone, Tone number (0-15) 

short note, Pitch specification in semitones (note number) (0-127) 

short fine, Detailed pitch specification (100/127 cents) (0-127) 

short voll, Volume, left (0-127) 

short voir) Volume, right (0-127) 

Explanation 





Keys on the voice specified by the VAB number, the program number (0-127), and the tone number (0-15) 
at the specified pitch and volume, and returns the allocated voice number. 





Return value 
The voice number (0-23) used for KeyOn. Returns -1 if unsuccessful. 


See also 
SsUtKeyOff() 
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Extended Sound Library Functions 14-107 





SsUtKeyOnV 

Key on a voice. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsUtKeyOnV( 

short voice, Voice number (0-23) 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

short prog, Program number (0-127) 

short tone, Tone number (0-15) 

short note, Pitch specification in semitones (note number) (0-127) 

short fine, Detailed pitch specification (100/127 cents) (0-127) 

short voll, Volume, left (0-127) 

short voir) Volume, right (0-127) 

Explanation 


Keys on the voice specified by the voice number (0-23), the VAB number, the program number (0-127), 
and the tone number (0-15) at the specified pitch and volume, and returns the allocated voice number. 








Return value 
The voice number (0-23) used for KeyOn. Returns -1 if unsuccessful. 


See also 
SsUtKeyOffv() 
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14-108 Extended Sound Library Functions 


SsUtPitchBend 
Apply a pitch bend. 
Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 
Syntax 
short SsUtPitchBend( 
short voice, Voice number (0-23) 
short vabld, VAB number (0-31) returned by SsVabOpenHead)() 
short prog, Program number (0-127) 
short note, Pitch specification in half-tone units (note number) (0-127) 
short pbend) Pitch-bend value (0-127) 
Explanation 


Applies a pitch bend (0-127, 64:center) to the voice. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtChangePitch(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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Extended Sound Library Functions 14-109 


SsUtReverbOff 


Turn off Reverb. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 
void SsUtReverbOff(voic) 


Explanation 
Turns off global Reverb. 


See also 
SsUtReverbOn() 
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14-110 Extended Sound Library Functions 


SsUtReverbOn 


Turn on Reverb. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 
void SsUtReverbOn(voia) 


Explanation 
Turns on global Reverb at the type and depth set by SsUtSetReverbType() and SsUtSetReverbDepth(). 


See also 
SsUtReverbOff(), SsUtSetReverbType(), SsUtSetReverbDepth() 
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Extended Sound Library Functions 14-111 





SsUtSetDetVVol 

Set a detailed value of voice volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsUtSetDetVVol( 

short vc, Voice number (0-23) 

short detvoll, Detailed volume, left (0-16383) 

short detvolr) Detailed volume, right (0- 16383) 

Explanation 





Sets the detailed value of voice volume. 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtGetDetWol(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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14-112 Extended Sound Library Functions 


SsUtSetProgAtr 

Set a program attribute table. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtSetProgAtr( 

short vabld, VAB number (0-31) from the return value of the function SsVabOpen() 

short progNum, Program number (0-127) 

ProgAtr “progatrptr) Pointer to program attribute table 

Explanation 


Specifies a VAB number and a program number, and changes the program attribute table, progatrptr. 


e Change allowed: mvol, mpan, prior, mode, attr 
e Change not allowed: tones, reservedO, reserved1, reserved2 








Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtGetProgAtr() 
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Extended Sound Library Functions 14-113 


SsUtSetReverbDelay 

Set a Delay volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsUtSetReverbDelay( 

short delay) 0-127 

Explanation 


Sets a delay time to be applied to Echo and Delay type reverb. 
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14-114 Extended Sound Library Functions 


SsUtSetReverbDepth 

Set a reverb depth. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsUtSetReverbDepth( 

short /depth, Left depth (0-127) 

short rdepth) Right depth (0-127) 

Explanation 


Sets a reverb depth. 


See also 
SsUtGetReverbT ype() 
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Extended Sound Library Functions 14-115 


SsUtSetReverbFeedback 


Set a feedback volume. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

void SsUtSetReverbFeedback( 

short feedback) Feedback (0-127) 

Explanation 


Sets a feedback volume to be applied Echo and Delay type reverb. 
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14-116 Extended Sound Library Functions 


SsUtSetReverbType 

Set reverb type. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsUtSetReverbType( 

short type) Reverb type 

Explanation 


Sets reverb type. 


Table 14-5: Reverb Type Overview (See Sound Delicatessen DSP) 











Type Mode Delay time Feedback 
SPU_REV_TYPE_OFF off X X 
SPU_REV_TYPE_ROOM room X X 
SPU_REV_TYPE_STUDIO_A studio (small) X X 
SPU_REV_TYPE_STUDIO_B studio (med) X X 
SPU_REV_TYPE_STUDIO_C studio (big) xX X 
SPU_REV_TYPE_HALL hall X X 
SPU_REV_TYPE_SPACE space echo X X 
SPU_REV_TYPE_ECHO echo Ø O 
SPU_REV_TYPE_DELAY delay O O 
SPU_REV_TYPE_PIPE pipe echo X X 





When a reverb type is set, reverb depth is automatically set to 0. Because noise occurs as soon as depth is 
set if data remains in the reverb work area, follow the procedure below: 


SsUtSetReverbType (SS_REV...); 
SsUtReverbOn(); 


Wait for several seconds. 
SsUtSetReverbDepth (64, 64); 





Return value 
The Type number that was set, if setting was correctly performed; otherwise -1. 


See also 
SsUtGetReverbType() 
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Extended Sound Library Functions 14-117 


SsUtSetVabHdr 
Set a VAB attribute header. 


Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtSetVabHadr( 

short vabld, VAB number (0-31) returned by SsVabOpenHead)() 

ValbHdr *vabharptr) Pointer to VAB attribute header 

Explanation 

Specifies the VAB number (the return value of SsVabOpenHead()) and changes the VAB attribute header, 

vabharptr. 


e Setting allowed: mvol, pan, attr1, attr2 only 
e Setting not allowed: form, ver, id, fsize, reserved0O, ps, ts, vs, reserved 1 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtGetVabHadr() 
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14-118 Extended Sound Library Functions 





SsUtSetVagAtr 

Set a tone attribute table (VagAtr). 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtSetVagAtr( 

short vabld, VAB number (0-31) from the return value of the function SsVabOpen() 

short progNum, Program number (0-127) 

short toneNum, Tone number (0-15) 

VagAtr *vagatrptr) Pointer to tone attribute table 

Explanation 

Specifies a VAB number, a program number, and a tone number, and changes a tone attribute table, 

vagatrptr. 


Change allowed: Items in VagAtr that are not listed below. 


Change not allowed: prog, vag, reserved7, reserved2, reservea[0-3] 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtGetVagAtr(), VagAtr() 
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Extended Sound Library Functions 14-119 


SsUtSetVVol 

Set voice volume. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 2.X 12/14/98 

Syntax 

short SsUtSetVVol( 

short vc, Voice number (0-23) 

short voll, Volume, left (0-127) 

short voir) Volume, right (0-127) 

Explanation 


Sets the left and right volumes of the specified voice, vc. Since libsnd uses an exponential volume 
calculation for sounds being keyed on, the input volumes voll and volr are modified as follows: 


lvol = vol*voll/127 
rvol = volr*volr/127 


Return value 
O if successful, -1 if unsuccessful. 


See also 
SsUtGetVVol(), SsUtKeyOn(), SsUtKeyOnV(), SsVoKeyOn() 
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14-120 Extended Sound Library Functions 


SsVabClose 
Close VAB data file. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 2.X 12/14/98 


Syntax 


void SsVabClose( 
short vab_id/) VAB data id 


Explanation 
Closes a VAB data file containing vab_id. 


Execute it after closing the SEQ/SEP which use the specified VAB data ID. 


See also 
SsVabOpen(), SsVab TransBody(), SsVabTransBodyPartly() 
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Extended Sound Library Functions 14-121 


SsVabFakeBody 

Assign a VAB ID to VAB data in the sound buffer. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsVabFakeBody( 

short vabid) VAB id 

Explanation 


After SsVabFakeHead() has established a VAB header in RAM, this function assigns a VAB ID to VAB body 
data that already exists in the sound buffer, without actually performing the transfer. It isn’t necessary to call 
SsVabTransCompleted)() after calling this function. 


SsVabFakeHead() and SsVabFakeBody() must be used together with SsVabOpenHeadSticky(); they cannot 
be used together with SsVabOpenHead)(). 


Return value 
VAB Identifying number. Returns -1 if unsuccessful. 


See also 
SsVabFakeHead(), SsVabOpenHeadSticky(), SsVabTransBody(), SsVabTransBodyPartly() 
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14-122 Extended Sound Library Functions 


SsVabFakeHead 

Open a new VAB header for a given VAB body. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 2/24/99 

Syntax 

short SsVabFakeHead( 

u_char “addr, Pointer to VH leading address 

short vabid, Desired VAB ID. If -1, the library makes the allocation. 

u_long sbadar) Address of VB inside the sound buffer. 

Explanation 


Associates new VAB header data with a given VabBody. 
When vabid is -1, the function searches for an empty VAB ID (0 - 15) and allocates it. 


sbadar is the starting address in the sound buffer of the VabBody. It is necessary to call SsVabFakeBody() 
next so that an actual data transfer doesn’t have to be performed. 


Since SsVabOpenHead(), SsVabFakeHead() and SsVabOpenHeadSticky() use and alter the system 
reserved area of the header list, the reserved area cannot be rewritten after header list recognition. 


SsVabFakeHead() and SsVabFakeBody() must be used together with SsVabOpenHeadSticky(); they cannot 
be used together with SsVabOpenHead)(). 








Return value 
VAB Identifying number. Returns -1 if unsuccessful. 


See also 
SsVabFakeBody(), SsUtGetVBaddrInSB(), SsVabOpenHead\(), SsVabOpenHeacdSticky() 
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Extended Sound Library Functions 14-123 


SsVabOpen 

Open VAB data. (Not recommended for use) 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsVabOpen( 

u_char “addr, Pointer to start address of VAB data in main storage 

ValbHdr *vab_header) Pointer to address to VAB header structure corresponding to VAB id 

Explanation 





Analyzes the VAB data header in main memory, stores the header value in vab_header, and returns the 
VAB id. It also transmits to the SPU local memory the VAG data group (wave form) data contained in VAB. 


Note: This function is no longer recommended for use. Instead, use SsVabOpenHead() and 
SsVabTransBody() or SsVabTransfer(). 


Return value 
VAB id identifying the given VAB. On failure, -1 is returned. 


See also 
SsVabClose(), SsVabOpenHead(), SsVabTransBody() 
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14-124 Extended Sound Library Functions 


SsVabOpenHead 
Open a VAB header. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 2/24/99 


Syntax 

short SsVabOpenHead( 

u_char *adar, Start address of VAB header (.VH) in main memory 
short vabiac) VAB ID 


Explanation 


Sets up a VAB header list in main memory so that it can be used by the Sound Library. A VAB ID may be 
specified to be used for opening, or if vabid is set to -1, the function allocates an empty VAB ID (O - 15) if 
there is one. Execute SsVabTransBody() to transfer the VAB body to the SPU RAM, and 
SsVabTransCompleted() to confirm completion of the transfer. 





This function reserves an area in SPU RAM for the VAB body in multiples of 64 bytes. Therefore, this area 
can be larger than the actual VAB body by up to 48 bytes (since the body is in sections of 16 bytes). 


Since SsVabOpenHead(), SsVabFakeHead() and SsVabOpenHeadSticky() use and alter the system 
reserved area of the header list, the reserved area cannot be rewritten after header list recognition. 








Return value 

VAB identification number. 

Returns -1 if unsuccessful. See error codes under SsVabOpenHeadSticky() for details. Also returns error if 
there isn’t enough room in SPU RAM for the VAB. 


See also 


SsVabTransBody(), SsVabTransBodyPartly(), SsVabOpenHeadSticky(), SsVabTransfer(), 
SsVabTransCompleted() 
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Extended Sound Library Functions 14-125 


SsVabOpenHeadSticky 

Open a VAB header and specify transfer address in sound buffer. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 2/24/99 

Syntax 

short SsVabOpenHeadSticky( 

u_char “addr, Start address of VAB header (.VH) in main memory 

short vabid, Desired VAB ID or -1 

u_long sbadar) Start address in sound buffer where VabBody is to be transferred 

Explanation 


Sets up a VAB header list in main memory so that it can be used by the sound library. vabid specifies a 
VAB ID to be opened; if vabid is set to -1, an empty VAB ID (0 - 15) is allocated, if there is one. 





Set sbadar to the address for transferring VabBody (.VB) to the sound buffer, within the range of 0x1010 
to Ox7ffff. Take the VabBody size into consideration so that doesn’t overwrite the reverb work area. 


Call SsVabTransBody() or SsVabTransBodyPartly() later to transfer VabBody to sbaddr. Since the .VB 
transfer is done in 64-byte usnits, the size written to the sound buffer may be larger than the actual .VB 
size. 








In general, you should either: 


e Use SsVabOpenHeadSticky() and do your own memory management, or 

e Use SsVabOpenHead() along with other routines that use libspu memory management, such as 
SsVabTransfer(), SouMalloc(), SouFree(), SouMallocWithStartAddr(), and 
SpuReserveReverbWorkArea(). 


If you combine these two approaches, the consistency of the sound buffer can’t be guaranteed. 


Since SsVabOpenHead(), SsVabFakeHead() and SsVabOpenHeadSticky() use and alter the system 
reserved area of the header list, the reserved area cannot be rewritten after header list recognition. 








Return value 
VAB identifying number. 


Returns -1 if unsuccessful, in the following cases: 


e The specified VabID was already open. 

e The specified VabID is not within the range 0-15. 

e The number of VABs allowed to be open simultaneously (16) was exceeded. 

e The VAB header doesn’t contain valid data. 

e The size of the VabBody to be transferred will go past the end of SPU RAM. 

e Could not confirm the end of the previous VabBody transfer using SsVabTransCompleted)(). 
See also 


SsVabOpenHead(), SsVabTransBody(), SsVaoTransBodyPartly(), SsVabTransfer() 
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14-126 Extended Sound Library Functions 


SsVabTransBody 


Transfer sound source data. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 

short SsVabTransBody( 

u_char *adar, VAB data start address 
short vabid) VAB ID 


Explanation 


After SsVabOpenHead)() recognizes a header list, this function starts transferring sound source data (VAB 
body) in main memory to SPU local memory. Data is transferred in 64-byte units. Use 
SsVabTransCompleted() to confirm transfer completion. 





The starting address (addr ) in the sound buffer into which VabBody(.VB) is transferred must be in the range 
Ox1010-Ox7ffff. It must take into account the size of the .VB, so that data is not transferred into the reverb 
work area. 


Return value 
VAB identifying number. Returns -1 if unsuccessful. 


See also 
SsVabOpenHead(), SsVabTransBodyPartly(), SsVabOpenHeadSticky(), SsVabTransfer() 
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Extended Sound Library Functions 14-127 


SsVabTransBodyPartly 

Transfer sound source data in segments. 
Library Header File Introduced Documentation Date 
libsnd. lib libsnd.h 3.0 12/14/98 

Syntax 

short SsVabTransBodyPartly( 

u_char *adar, Pointer to starting address of the segment transfer buffer 

u_long bufsize, Buffer size 

short vabia) VAB ID 

Explanation 


Starts transferring a VAB body in main memory, whose VAB header was opened with SsVabOpenHead\(), 
to the sound buffer. 


By continuously calling SsVabTransBodyPartly() while sequentially copying part of the sound source (VAB 
body) into the area indicated by addr with a size of bufsize, transfers may be made to a contiguous area 
within the sound buffer using only a limited area in main memory. 


Since data is transferred in 64-byte units, bufsize must be a multiple of 64. 





You must call SsVabTransCompleted() to verify whether each transfer has been completed before calling 
SsVabTransBodyPartly() again. 


Return value 
vabid, if transfer successful. Error codes are: 


-2: The size of the sound source data (VAB body) inherited from 
SsVabOpenHead)() has not been completely transferred 

-1: Transfer failed 

See also 


SsVabOpenHead\(), SsVabTransBody(), SsVabOpenHeadSticky(), SsVabTransfer() 
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14-128 Extended Sound Library Functions 


SsVabTransCompleted 

Get VAB data transfer state. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

short SsVabTransCompleted( 

short immediateFilag) Transfer status recognition flag 

Explanation 


Determines whether data transfer to SPU local memory has terminated. 


If inmediateFlag is SS_IMMEDIATE, the function returns the transfer state immediately. If immediateFlag is 
SS_WAIT_COMPLETED, the function loops until transfer is completed. 





Return value 
1 if the transfer has been completed, O if the transfer is ongoing. 


See also 
SsVabOpenHead\(), SsVabOpenHeadSticky(), SsVabTransfer(). SsVabTransBody(), SsVabTransBodyPartly() 
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Extended Sound Library Functions 14-129 


SsVabTransfer 

Recognize and transfer sound source data. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

SsVabTransfer( 

u_char *vh_adar, Pointer to VH data 

u_char *vb_addr, Pointer to VB data 

short vabid, VAB ID number 

short /_flag) = SS_IMMEDIATE...Immediately returns return value (VAB ID number) 


= SS_WAIT_COMPLETED...Waits until transfer is completed 


Explanation 

Recognizes a sound source header list (VH data) specified by vh_adadr and transfers sound source data (VB 
data) specified by vb_adar, to the sound buffer. The VAB ID number is specified in the argument vabid. 
When vabid is -1, the function searches for an empty VAB ID (0-15) and allocates it. /_flag determines 
whether the function should wait until transfer is completed or return immediately after the transfer starts, 
then check with SsVabTransCompleted(). 


Return value 
VAB ID number, if successful. Error codes are: 


-1: VAB ID cannot be allocated or invalid VH 
-2: Invalid VB 

-3 and lower: Other error 

See also 


SsVabOpenHead(), SsVabOpenHeadSticky(), SsVabTransBody(), SsVabTransBodyPartly(), 
SsVabTransCompleted() 
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SsVoiceCheck 

Verify tone information played by a voice that is to be modified. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 4.1 12/14/98 

Syntax 

short SsVoiceCheck( 

long voice, Voice number containing tone information to be verified (0-23) 

long vabid, The upper 8 bits of the lower 2 bytes of vab/d contain the VAB ID returned 


by SsVabOpenHead)(), and the lower 8 bits of the lower 2 bytes of vabld 
contain the program number containing the tone information to be verified 
short note) The note at which the tone to be verified was originally keyed on 





Explanation 

Verifies that the tone information played by a voice that is to be modified (key off, reverb change, pitch 
change etc.) is the intended tone information; that is, that the voice was not allocated to a different tone 
than the tone specified by vabid and note. 





Should be called before each call to SsQueueRegisters() after key on of sound has occurred. 


Return value 


O if successful; -1 if tone information is different than tone specified by vab/d and note or voice is out of 
range. 


See also 


SndRegisterAttr(), SndVoiceStats(), SndVolume2(), SsAllocateVoices(), SsBlockVoiceAllocation(), 
SsGetActualProgFromProg(), SsPitchFromNote(), SsQueueKeyOn(), SsQueueRegisters(), SsQueueReverb(), 
SsSetVoiceSettings(), SsUnBlockVoiceAllocation() 
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Extended Sound Library Functions 14-131 


SsVoKeyOff 
Key off. 


Library Header File Introduced Documentation Date 
libsnd.lib libsnd.h 3.0 12/14/98 


Syntax 

long SsVoKeyOff( 

long vab_pro, VAB data id and program number 
long pitch) Pitch 

Explanation 


Of the lower 16 bits of vab_pro, the upper 8 bits are used for VAB id, and the lower 8 bits specify a 
program number. Of the lower 16 bits of pitch, the upper 8 bits specify a key number in MIDI standard. To 
specify a finer pitch, specify a key number in the lower 8 bits of pitch in 1/128 semitones. 


Return value 
The keyed off voice number. 


See also 
SsVoKeyOn() 
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14-132 Extended Sound Library Functions 


SsVoKeyOn 

Key on. 
Library Header File Introduced Documentation Date 
liosnd.lib liosnd.h 3.0 12/14/98 

Syntax 

long SsVoKeyOn( 

long vab_pro, VAB data id and program number 

long pitch, Pitch 

u_short volL, L channel volume 

u_short vo/R) R channel volume 

Explanation 


Of the lower 16 bits of vab_pro, the upper 8 bits are used for VAB id, and the lower 8 bits specify a 
program number. Of the lower 16 bits of pitch, the upper 8 bits specify a key number in MIDI standard. To 
specify a finer pitch, specify a key number in the lower 8 bits of pitch in 1/128 semitone units. The sound 
specified by vab_pro and pitch is keyed on at the specified voll and volr. 


KeyOn with volume set to 0 is the same as SsVoKeyOff(). 


Return value 


Voices which were keyed on. To determine if a specific voice was keyed on, AND the return value and the 
appropriate voice bit SPU_xxCH (xx=0-23). If the value is non-zero, the voice was keyed on. 





See also 
SsVoKeyOff() 
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Basic Sound Library Structures 15-5 





SpuCommonAttr 
Common attributes. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 2.X 12/14/98 
Structure 
typedef struct { 
u_long mask; Set mask 
SpuVolume mvol; Master volume 
SpuVolume mvolmode; Master volume mode 
SpuVolume mvolx; Current master volume 
SpuExtAttr cd; Cd input attributes 
SpuExtAttr ext; External digital input attributes 
} SouCommonAttr; 
Explanation 


Used when setting/checking common attributes. The members needed for setting are set as bit values in 
mask, 





See also 
SpuVolume(), SpuExtAttr(?), SouSetCommonaAttr(), SouGetCommonaAttr() 
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15-6 Basic Sound Library Structures 


SpuDecodeData 
Decoded data from SPU. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 2.X 12/14/98 


Structure 
#define SPU_DECODEDATA_SIZE 0x200 


typedef struct { 
short cd_left{SPU_DECODEDATA_SIZE]; CD L channel data decoded by SPU 
short cd_right{SPU_DECODEDATA_SIZE]; CD R channel data decoded by SPU 
short voice1/SPU_DECODEDATA_SIZE]; Voice 1 data decoded by SPU 
short voice3/SPU_DECODEDATA_SIZE]; Voice 3 data decoded by SPU 

} SpuDecodeData; 


Explanation 


This structure describes an area used when getting CD-ROM, voice 1 and voice 3 data decoded by the 
SPU. Each member specifies a buffer for that type of data. Note that the sizes shown are in short 
integers, so total size of SouDecodeData region is 0x1000 bytes. 





When you call SouReadDecodedData(), the SPU copies data from its buffers to the SouDecodeData struct 
in main memory that you specify. It copies the data one-half buffer (0x200 bytes) at a time, and returns a 
code specifying which half of the buffer is currently being written to, so you can use the data from the other 
half. 





See also 
SpuReadDecodedData() 
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SpuEnv 
SPU environment attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 2.X 12/14/98 


Structure 
typedef struct { 
u_long mask; Setting mask 
u_long queueing; Event queueing 
} SpuEnv; 
Explanation 
Used to set the basic sound library environment. Currently, only queueing of the following events can be set 
- Key on, Key off, Pitch LFO voice setting, Noise Voice setting, and Reverb Voice setting. 


The default value state is to perform the setting of these events immediately. 


See also 
SpuSetEnv(), SouFlush() 
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SpuExtAttr 


External input attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 2.X 12/14/98 


Structure 
typedef struct { 
SpuVolume volume; Volume 
long reverb; Reverb on/off 
long mix; Mixing on/off 
} SpuExtAttr; 
Explanation 
Used when setting/checking CD and external digital input attributes. 


See also 
SpuCommonAttr(), SouVolume() 
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SpuLVoiceAttr 


Voice attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 4.4 12/14/98 


Structure 

typedef struct { 
short voiceNum; Voice number (0-23) 
short pad; 
SpuVoiceAttr attr; Voice attributes 

} SpuLVoiceAttr; 


Explanation 


Specifies voice attributes for a specific voice. An array of SouLVoiceAttr structures is passed to 
SpuLSetVoiceAttr() to set attributes for multiple voices. 





voiceNum specifies the voice for which the attributes should be set. attr.voice settings are ignored. 


See also 
SpuGetVoiceAttr(), SouSetVoiceAttr(), SouLSetVoiceAttr() 


CONFIDENTIAL Run-Time Library Reference 


15-10 Basic Sound Library Structures 


SpuReverbAttr 
Reverb attributes. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 
Structure 
typedef struct { 
u_long mask; Set mask 
long mode; Reverb mode 
SpuVolume depth; Reverb depth 
long delay; DelayTime (ECHO, DELAY only) 
long feedback; Feedback (ECHO, DELAY only) 
} SpuReverbAttr; 
Explanation 
Used when setting/checking reverb attributes. The members required at setting are set in the mask as bit 
values. 
See also 


SpuSetReverbModeParam(), SouGetReverbModeParam(), SouSetReverbDepth() 


Run-Time Library Reference CONFIDENTIAL 





Basic Sound Library Structures 15-11 


SpuStEnv 
SPU streaming environment attributes. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 2.X 12/14/98 
Structure 
typedef struct { 
long size; Stream buffer size 
long /ow_priority; Determines priority of SPU Streaming compared to other 


CPU processes. Default is SPU_OFF. Setting to SPU_ON 
lowers SPU Streaming priority. 
SpuStVoiceAttr voice/24]; Each stream attribute set 
} SpuStEnv 
Explanation 
Used in SPU streaming library, streaming environment and stream attribute setting. 


See also 
SpuStlnit() 
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SpuStVoiceAttr 
SPU streaming voice attributes. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Structure 
typedef struct { 
char status; Stream status 
char pad1, pad2, pad3; Padding 
long /ast_size; Size of final data transfer ( <= (size / 2)) 
u_long buf_addr; Start address of stream buffer 
u_long data_addr; Start address of stream data in main RAM 
} SpuStVoiceAttr; 
Explanation 





Contains attributes for each stream used by the SPU streaming library. See also SpuStEnv. 


See also 
SpuStlnit() 
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SpuVoiceAttr 


Voice attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Structure 
typedef struct { 


u_long voice; 
u_long mask; 
SpuVolume volume; 
SpuVolume volmode; 
SpuVolume volumex; 
u_short pitch; 
u_short note; 


u_short sample_note; 


Voice (low 24 bits are a bit string, 1 bit per voice ) 
Attributes (bit string, 1 bit per attribute) 

Volume 

Volume mode 

Current volume 

Interval (set pitch) 

Interval (set note) 

Interval (set note) 





short envx; Current envelope volume value 
u_long addr; Waveform data start address 
u_long /oop_addr; Starting address of loop 
long a_mode; Attack rate mode 

long s_mode; Sustain rate mode 

long r_mode; Release rate mode 

u_short ar; Attack rate 

u_short dr; Decay rate 

u_short sr; Sustain rate 

u_short rr; Release rate 

u_short sl; Sustain level 


u_short adsr1; 
u_short adsr2; 


Same value as structure VagAtr adsr1 
Same value as structure VagAtr adsr2 


} SpuVoiceAttr; 


Explanation 


Used when setting/checking the attributes of each voice. The voice number is provided/obtained from the 
voice bit value, and the members needed for setting are set as bit values in the mask. 





Note: Constant macro names spelled SPU_ON, SPU_OFF have the same values as and are 
interchangeable with constant macros used in the program and spelled SpuOn, SpuOff. 


See also 
SpuSetVoiceAttr(), SouGetVoiceAttr(), SouSetKeyOnWithAttr() 
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15-14 Basic Sound Library Structures 


SpuVolume 
Volume. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 2.X 12/14/98 


Structure 


typedef struct { 
short /eft; L channel value 
short right; R channel value 
} SpuVolume; 


Explanation 
Used in attributes that require L channel/R channel values when setting/getting each voice. 





See also 
SpuVoiceAttr(), SouReverbAttr(), SouExtAttr(), SouCommonaAttr() 
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Basic Sound Library Functions 


SpuClearReverbWorkArea 


Clear reverb work area. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

long SpuClearReverbWorkArea( 

long rev_mode) Reverb mode 

Explanation 


Clears the area occupied by the reverb work area corresponding to the reverb mode rev_mode. 
Regardless of whether or not it is reserved at this time, the function checks to see if the area is being used. 


This operation uses synchronous DMA transfer, so it blocks until finished. The time taken depends on the 
reverb mode; it should take a maximum of 1/5 second. 


This function should not be called while another Spu transfer is occurring, as the SpuSetTransferCallback is 
temporarily cleared inside this function and thus the end of the pending transfer may be missed. 


Return value 


O if successful. SPU_ERROR is returned if the reverb work area corresponding to rev_mode is in use, or if 
the specified reverb mode value is wrong. 








See also 
SpuSetReverbModeParam(), SouReserveReverbWorkArea(), SouSetReverb(), SouMalloc(, 
SpuMallocWithStartAddr() 
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15-15 


15-16 Basic Sound Library Functions 


SpuFlush 


Flush queued events. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 
u_long SpuFlush( 
u_long ev) Event to be flushed 


Explanation 
Flushes a queued event. 


Set ev with bitwise inclusive ORed events to be flushed: 


SPU_EVENT_KEY Key ON/OFF 
SPU_EVENT_PITCHLFO Pitch LFO Voice Set 
SPU_EVENT_NOISE Noise Voice Set 
SPU_EVENT_REVERB Reverb Voice Set 


When ev is set to SPU_EVENT_ALL, all events are flushed. 


Return value 
Bitwise inclusive ORed value of the flushed event(s). 





See also 
SpuSetEnv(), SouSetKey(), SouSetKeyOnWithAttr(), SpuSetPitchLFOVoice(), SouSetNoiseVoice(), 
SpuSetReverbVoice() 
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Basic Sound Library Functions 15-17 


SpuFree 
Release area allocated in sound buffer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Syntax 
void SpuFree( 
u_long addr Start address of allocated area (in bytes) 
Explanation 


Releases area allocated in the sound buffer as indicated by the start address addr, and deletes that area's 
information from the management table. 


See also 
SpulnitMalloc(), SpuMalloc(), SouMallocWithStartAddr() 
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15-18 Basic Sound Library Functions 


SpuGetAllKeysStatus 

Determine key on/off for all voices. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

void SpuGetAllKeysStatus( 

char *status) Pointer to the result of checking a voice (24 bytes) 

Explanation 


Checks key on/key off and envelope status of all voices. status is a 24-byte array containing the key 
on/key off and envelope status of each voice. 


See Table 15-1 under SouGetKeyStatus() for information about the values that can be returned. 


See also 
SpuSetKey(), SouGetKeyStatus(), SouRGetAllKeysStatus() 
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Basic Sound Library Functions 15-19 


SpuGetCommonAttr 

Check sound system attributes 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

void SpuGetCommonAttr( 

SpuCommonaAttr “attr Pointer to attributes common to all voices 

Explanation 


Returns sound system attributes in attr. See SouSetCommonAttr() for details. 


See also 
SpuSetCommonAttr(), SouCommonaAttr() 
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15-20 Basic Sound Library Functions 


SpuGetCommonCDMix 
Get CD input on/off status. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 
Syntax 
void SpuGetCommonCDMix( 
long *on_off) CD input on/off 
Explanation 
Gets the CD input on/off status. Equivalent to getting cd. mix member of SouCommonAttr using 
SpuGetCommonAttr(). 
See also 


SpuGetCommonaAttr(), SouSetCommonCDMix() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-21 


SpuGetCommonCDReverb 

Get CD input reverb on/off status. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetCommonCDReverb( 

long *on_off) CD input reverb on/off 

Explanation 


Gets the CD input reverb on/off status. Equivalent to getting cd.reverb member of SouCommonAttr using 
SpuGetCommonAttr(). 


See also 
SpuGetCommonaAttr(), SpuSetCommonCDReverb() 
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15-22 Basic Sound Library Functions 


SpuGetCommonCDVolume 
Get CD input volume. 
Library Header File Introduced Documentation Date 


libspu.lib libspu.h 3.7 12/14/98 


Syntax 

void SpuGetCommonCDVolume( 

short *cavolL, CD Input volume (left) 
short *cdvo/R) CD Input volume (right) 
Explanation 


Gets the CD input volume. Equivalent to getting cd. volume member of SouCommonAttr using 
SpuGetCommonAttr(). 


See also 
SpuGetCommonaAttr(), SouSetCommonCDVolume() 
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Basic Sound Library Functions 15-23 


SpuGetCommonMasterVolume 


Get master volume. 





Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SouGetCommonMasterVolume( 

short *mvolL, Master volume (left) 

short *mvolR) Master volume (right) 

Explanation 





Gets master volume. Equivalent to getting mvo’ member of SouCommonAttr using SouGetCommonAttr(). 


The value is valid only when the volume mode is ‘direct mode’. Other volume modes are undefined. 





When the volume mode is not ‘direct mode’, or to get both the volume and the volume mode at the same 
time, use SouGetCommonMasterVolumeAttr(). 


See also 


SpuGetCommonaAttr(), SouGetCommonMasterVolumeAttr(), SouSetCommonMasterVolume(), 
SpuSetCommonMasterVolumeAttr() 
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15-24 Basic Sound Library Functions 


SpuGetCommonMasterVolumeAttr 


Get master volume/master volume mode. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SouGetCommonMasterVolumeAttr( 

short *mvolL, Master volume (left) 

short *mvolR, Master volume (right) 

short *mvolModeL, Master Volume Mode (left) 

short *mvolModeR) Master Volume Mode (right) 

Explanation 


Gets the master volume/master volume mode. Equivalent to getting mvo/ and mvolmode members of the 
SpuCommonAttr using SouGetCommonAttr(). 





See also 


SpuGetCommonaAttr(), SouGetCommonMasterVolume(), SouSetCommonMasterVolume(), 
SpuSetCommonMasterVolumeAttr() 
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Basic Sound Library Functions 15-25 


SpuGetCommonMasterVolumeX 


Get current master volume. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetCommonMasterVolumeX( 

short *mvolXL, Current master volume (left) 

short *mvolXR) Current master volume (right) 

Explanation 


Gets the current master volume. Equivalent to getting mvolx member of SouCommonAttr using 
SpuGetCommonAttr(). 


See also 


SpuGetCommonAttr(), SouGetCommonMasterVolume(), SouGetCommonMasterVolumeAttr(), 
SpuSetCommonMasterVolume(), SouSetCommonMasterVolumeAttr() 
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15-26 Basic Sound Library Functions 


SpuGetiIRQ 


Check status of interrupt request. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 
long SpuGetIRQ(voia) 


Explanation 
Checks status of interrupt request. 


Return value 


SPU_ON Interrupt request is set 
SPU_OFF Interrupt request is not set 
See also 

SpuSetIRQ() 
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Basic Sound Library Functions 15-27 


SpuGetIRQAddr 

Check interrupt request address. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuGetIRQAddr(voia) 

Explanation 


Returns interrupt request address value. 


Return value 
Currently set address. 


See also 
SpuSetIRQAddr(), SpuSetIRQ() 
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15-28 Basic Sound Library Functions 


SpuGetKeyStatus 

Check key on/key off status for a voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuGetKeyStatus( 

u_long voice_bit) Checked voice 

Explanation 


Checks key on/key off and envelope status for a voice specified in voice_bit with one of the values 
SPU_OCH ... SPU_23CH. (If multiple bits are set, the smallest voice number set is selected.) 





Return value 


If successful, the current key on/key off status and envelope status of the specified voice are returned. (See 
the table below.) If the specified voice is incorrect, -1 is returned. 


Table 15-1: Key and Envelope Status Values 
Value Status Description 
SPU_ON Key on status Sound currently playing. 
Not turned off by SpuSetKey() 
Envelope not O 








SPU_ON_ENV_OFF Key on status Sound either about to start 
Not turned off by SpuSetKey() playing, or non-looping 
Envelope O sound expired. 

SPU_OFF_ENV_ON Key off status Sound in release state. 


Turned off by SouSetKey() 
Envelope not O 
SPU_OFF Key off status Sound off. 
Turned off by SouSetKey() 
Envelope O 





See also 
SpuSetKey(), SouGetAllKeysStatus() 
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Basic Sound Library Functions 15-29 


SpuGetMute 

Check sound muting status. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 


long SpuGetMute(voic) 


Explanation 
Checks current sound mute on/off status. 


Return value 


SPU_ON Mute off 
SPU_OFF Mute on 
See also 

SpuSetMute() 
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15-30 Basic Sound Library Functions 


SpuGetNoiseClock 

Check noise source clock. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 


long SpuGetNoiseClock(voic) 


Explanation 
Returns the value of the noise source clock. 


Return value 
Current noise source clock value. 


See also 
SpuSetNoiseClock() 
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Basic Sound Library Functions 15-31 


SpuGetNoiseVoice 

Check noise source ON/OFF for each voice 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 


u_long SpuGetNoiseVoice(voic) 
Explanation 
Checks current status of noise source ON/OFF for each voice. 


Return value 


An unsigned long with 1 bit set for each voice whose noise source is on. To check a voice, AND this value 
with the bit mask for the voice (SPU_OCH...SPU_23CH). If the value is non-zero, the noise source is on. 


See also 
SpuSetNoiseClock(), SouSetNoiseVoice() 


CONFIDENTIAL Run-Time Library Reference 


15-32 Basic Sound Library Functions 


SpuGetPitchLFOVoice 

Check pitch LFO ON/OFF for each voice. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuGetPitchLFOVoice(voic) 

Explanation 


Checks current status of pitch LFO ON/OFF for each voice. 


Return value 


An unsigned long with 1 bit set for each voice whose pitch LFO is on. To check a voice, AND this value 
with the bit mask for the voice (GPU_OCH...SPU_23CH). If the value is non-zero, the pitch LFO is on. 


See also 
SpuSetPitchLFOVoice() 
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Basic Sound Library Functions 15-33 


SpuGetReverb 

Check reverb status. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 


long SpuGetReverb(voic) 


Explanation 
Checks current reverb ON/OFF status. 


Return value 


SPU_ON Reverb on 
SPU_OFF Reverb off 
See also 

SpuSetReverb() 
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15-34 Basic Sound Library Functions 


SpuGetReverbModeDelayTime 


Get reverb mode delay time. 





Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetReverbModeDelayTime( 

long *delay) Reverb delay time 

Explanation 


Gets the reverb delay time. Equivalent to getting delay member of SouReverbAttr using 
SpuGetReverbModeParam(). 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam(), SouSetReverb ModeDelayTime() 
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Basic Sound Library Functions 15-35 


SpuGetReverbModeDepth 
Get reverb mode depth. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetReverbModeDepth( 

short *depthL, Reverb depth (left) 

short *depthR) Reverb depth (right) 

Explanation 


Gets the reverb depth. Equivalent to getting depth member of SpuReverbAttr using 
SpuGetReverbModeParam(). 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam(), SouSetReverbModeDepth() 
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15-36 Basic Sound Library Functions 


SpuGetReverbModeFeedback 


Get reverb mode feedback. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetReverbModeFeedback( 

long *feedback) Reverb feedback 

Explanation 


Gets the reverb feedback. Equivalent to getting feedback member of SpuReverbAttr using 
SpuGetReverbModeParam(). 


See also 
SpuSetReverobModeParam(), SouGetReverobModeParam(), SouSetReveroModeFeedback() 
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Basic Sound Library Functions 15-37 


SpuGetReverbModeParam 


Check reverb mode and parameters. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

void SpuGetReverbModeParam( 

SpuReverbAttr “attr Pointer to reverb attributes 

Explanation 


Gets currently set reverb mode and parameters. For details see SouSetReverbModeParam(). 


See also 
SpuSetReverbModeParam(), SouReverbAttr() 
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15-38 Basic Sound Library Functions 


SpuGetReverbModeType 

Get reverb mode type. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuGetReverbModeType( 

long *type) Reverb mode type 

Explanation 


Gets the reverb mode type. Equivalent to getting mode member of SpuReverbAttr using 
SpuGetReverbModeParam(). 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam(), SouSetReverbModeType() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-39 


SpuGetReverbVoice 

Check reverb ON/OFF for each voice. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 


u_long SpuGetReverbVoice(voia) 
Explanation 
Checks current reverb ON/OFF status for each voice. 


Return value 


An unsigned long with 1 bit set for each voice whose reverb status is on. To check a voice, AND this value 
with the bit mask for the voice (SPU_OCH...SPU_283CH). If the value is non-zero, reverb is on. 


See also 
SpuSetReverbVoice() 
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15-40 Basic Sound Library Functions 


SpuGetTransferMode 

Get sound buffer transfer mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 


long SpuGetTransferMode(voic) 
Explanation 
Returns current value of the transfer mode when transferring from main memory to the sound buffer. 


Return value 
Current setting of transfer mode: 


SPU_TRANSFER_BY_DMA DMA transfer setting 
SPU_TRANSFER_BY_IO I/O transfer setting 
See also 


SpuSetTransferMode(), SouWrite(), SouWriteO(), SpuWritePartly() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-41 


SpuGetTransferStartAddr 


Get sound buffer transfer start address. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Syntax 


u_long SpuGetTransferStartAddr(voia) 


Explanation 
Returns current start address for transferring between main memory and the sound buffer. 


Return value 
Current sound buffer transfer start address. 


See also 
SpuSetTransferStartAddr(), SouWrite(), SouWriteO(), SouWritePartly(), SouRead(), SouReadDecodedData() 
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15-42 Basic Sound Library Functions 


SpuGetVoiceADSR 

Get ADSR. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceADSR( 

int voiceNum, Voice number (0 - 23) 

u_short *AR, ADSR attack rate 

u_short “DR, ADSR decay rate 

u_short *SR, ADSR sustain rate 

u_short *RR, ADSR release rate 

u_short *SL) ADSR sustain level 

Explanation 


Gets each ADSR attribute used in the voice. Equivalent to getting SpuVoiceAttr members ar, ar, sr, rr, and 
sl using SpuGetVoiceAttr(). 





The values are valid only for the following attack, sustain, and release rate modes. For other modes, the 
values are undefined. 


e Attack Rate Mode: SPU_VOICE_LINEARIncN (Linear Increase) 
e Sustain Rate Mode: SPU_VOICE_LINEARDecN (Linear Decrease) 
e Release_Rate_Mode: SPU_VOICE_LINEARDecN_(Linear Decrease) 


To get multiple rates at the same time, use SouSetVoiceADSRAttr(). 











See also 


SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceAR(), SouGetVoiceDR(), SouGetVoiceSR(), 
SpuGetVoiceRR(), SouGetVoiceSL() 
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Basic Sound Library Functions 15-43 





SpuGetVoiceADSRAttr 

Get ADSR rates and modes. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceADSRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short *AR, ADSR attack rate 

u_short “DR, ADSR decay rate 

u_short *SR, ADSR sustain rate 

u_short *RR, ADSR release rate 

u_short *SL, ADSR sustain level 

long *ARmode, ADSR attack rate mode 

long *SRmode, ADSR sustain rate mode 

long *RRmode) ADSR release rate mode 

Explanaton 


Gets each ADSR attribute used in the voice. Equivalent to getting SpuVoiceAttr members ar, dr, sr, rr, Sl, 
a_mode, s_mode, and r_mode using SpuGetVoiceAttr(). 


See also 

SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceADSR(), SouGetVoiceAR(), SouGetVoiceDR(, 
SpuGetVoiceSR(), SouGetVoiceRR(), SouGetVoiceSL(), SouGetVoiceARAttr(), SouGetVoiceSRAttr(), 
SpuGetVoiceRRAttr() 
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15-44 Basic Sound Library Functions 


SpuGetVoiceAR 
Get ADSR attack rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoiceAR( 

int voiceNum, Voice number (0 - 23) 

u_short *AR) ADSR attack rate 

Explanation 

Gets ADSR attack rate for a voice. Equivalent to getting SpuVoiceAttr member ar using SouGetVoiceAttr(). 


The value is valid only when the attack rate mode is SPU_VOICE_LINEARIncN (Linear Increase). For other 
modes, the value is undefined. 





To get both attack rate and attack rate mode at the same time, use SouGetVoiceARAttr(). 





See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceARAttr() 
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Basic Sound Library Functions 15-45 


SpuGetVoiceARAttr 

Get ADSR attack rate / attack rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceARAttr( 

int voiceNum, Voice number (0 - 23) 

u_short *AR, ADSR attack rate 

long *ARmode) ADSR attack rate mode 

Explanation 


Gets ADSR attack rate and attack rate mode for a voice. Equivalent to getting SpuVoiceAttr members ar 
and a_mode using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceAR() 
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15-46 Basic Sound Library Functions 


SpuGetVoiceAttr 


Get voice attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 


void SpuGetVoiceAttr( 
SpuVoiceAttr “attr Pointer to voice attributes 


Explanation 


Gets the attributes for a single voice that you specify in attr.voice (with one of the values SPU_OCH ... 





SPU_23CH). All the SpuVoiceAttr structure members are returned in attr except attr.mask. See 
SpuSetVoiceAttr() for the details of these attributes. 


See also 
SpuSetVoiceAttr(), SouRSetVoiceAttr(), SouSetKey(), SouSetKeyOnWithAttr(), SouVoiceAttr() 
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Basic Sound Library Functions 15-47 


SpuGetVoiceDR 
Get ADSR decay rate. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceDR( 

int voiceNum, Voice number (0 - 23) 

u_short *DR) ADSR decay rate 

Explanation 

Gets ADSR decay rate for voice. Equivalent to getting SouVoiceAttr member dr using SouGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr() 
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15-48 Basic Sound Library Functions 


SpuGetVoiceEnvelope 
Get current envelope value. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoiceEnvelope( 

int voiceNum, Voice number (0 - 23) 
short *envx) Current envelope value 





Explanation 
Gets the current envelope value for a voice. Equivalent to getting the SpuVoiceAttr member envx, using 
SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr() 
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Basic Sound Library Functions 15-49 


SpuGetVoiceEnvelopeAttr 


Get current envelope value and key ON/OFF status. 





Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceEnvelopeAttr( 

int voiceNum, Voice number (0 - 23) 

long *keyStat, Status of voice envelope and key ON/OFF 

short *envx) Current envelope value 

Explanation 


Gets the current envelope value, key ON/OFF and envelope status for a voice. 
Refer to Table 15-1 in under SpuGetKeyStatus() for the key ON/OFF and envelope status values that can 
be specified in keyStat. 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceEnvelope(), SouSetKey(), SouGetAllKeysStatus(), 
SpuRGetAllKeysStatus() 
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15-50 Basic Sound Library Functions 


SpuGetVoiceLoopStartAddr 


Get loop start address of waveform data in the sound buffer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceLoopStartAddr( 

int voiceNum, Voice number (0 - 23) 

u_long *“/oopStartAdar) Loop start address 

Explanation 


Gets loop start address of waveform data in the sound buffer. Equivalent to getting SouVoiceAttr member 
loop_adar using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetTransferStartAddr() 
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Basic Sound Library Functions 15-51 


SpuGetVoiceNote 
Get interval (note specification). 
Library Header File Introduced Documentation Date 


libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoiceNote( 

int voiceNum, Voice number (0 - 23) 

u_short *note) Interval (note specification) 

Explanation 

Gets Voice Interval (Note Specification). Equivalent to getting SpuVoiceAttr member note using 
SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceSampleNote(), SouGetVoiceSampleNote() 
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15-52 Basic Sound Library Functions 


SpuGetVoicePitch 


Get interval (pitch specification). 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoicePitch( 

int voiceNum, Voice number (0 - 23) 

u_short “pitch) Interval (pitch specification) 

Explanation 

Gets voice interval (pitch specification). Equivalent to getting SpuVoiceAttr member pitch using 
SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr() 
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Basic Sound Library Functions 15-53 


SpuGetVoiceRR 
Get ADSR release rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoiceRR( 

int voiceNum, Voice number (0 - 23) 

u_short *RR) ADSR release rate 

Explanation 

Gets ADSR release rate for a voice. Equivalent to getting SouVoiceAttr member rr using SouGetVoiceAttr(). 





The value is valid only when the release rate mode is SPU_VOICE_LINEARDecN (Linear Decrease mode). 
For other release rate modes, the value is undefined. 


To get release rate and release rate mode at the same time, use SouGetVoiceRRAttr(). 





See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceRRAttr() 
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15-54 Basic Sound Library Functions 





SpuGetVoiceRRAttr 

Get ADSR release rate / release rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceRRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short *RR, ADSR release rate 

long *RRmode) ADSR release rate mode 

Explanation 





Gets ADSR release rate / ADSR release rate mode for a voice. Equivalent to getting SpuVoiceAttr 
members rr and r_mode using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceRR() 
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Basic Sound Library Functions 15-55 


SpuGetVoiceSampleNote 


Get waveform data sample note. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceSampleNote( 

int voiceNum, Voice number (0 - 23) 

u_short *“sampleNote) Sets waveform data sample note 

Explanation 


Gets waveform data sample note. Equivalent to getting SouVoiceAttr member sample_note using 
SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceNote() 
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15-56 Basic Sound Library Functions 


SpuGetVoiceSL 
Get ADSR sustain level. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceSL( 

int voiceNum, Voice number (0 - 23) 

u_short *SL) ADSR sustain level 

Explanation 

Gets ADSR sustain level. Equivalent to getting SouVoiceAttr member sl using SouGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceRRAttr() 
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Basic Sound Library Functions 15-57 


SpuGetVoiceSR 
Get ADSR sustain rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuGetVoiceSR( 

int voiceNum, Voice number (0 - 23) 

u_short *SA) ADSR sustain rate 

Explanation 

Gets ADSR sustain rate in a voice. Equivalent to getting SouVoiceAttr member sr using SpuGetVoiceAttr(). 





The value is valid only when sustain rate mode is SPU_VOICE_LINEARDecN (Linear Decrease mode). For 
other sustain rate modes, the value is undefined. 





To get both sustain rate and sustain rate mode at the same time, use SouGetVoiceSRAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceSRAttr() 
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15-58 Basic Sound Library Functions 


SpuGetVoiceSRAttr 

Get ADSR sustain rate and sustain rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceSRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short *SR, ADSR sustain rate 

long *SRmode) ADSR sustain rate mode 

Explanation 


Gets ADSR sustain rate and ADSR sustain rate mode for voice. Equivalent to getting SouVoiceAttr 
members sr and s_mode using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceSR() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-59 


SpuGetVoiceStartAddr 

Get address of waveform data in the sound buffer. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceStartAddr( 

int voiceNum, Voice number (0 - 23) 

u_long *startAddr) Waveform data start address 

Explanation 


Gets start address of waveform data in the sound buffer. Equivalent to getting SpuVoiceAttr member addr 
using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetTransferStartAddr() 


CONFIDENTIAL Run-Time Library Reference 


15-60 Basic Sound Library Functions 


SpuGetVoiceVolume 

Get voice volume. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceVolume( 

int voiceNum, Voice Number (0 - 23) 

short *volumeL, Volume (Left) 

short *volumeR) Volume (Right) 

Explanation 


Gets voice volume. Equivalent to getting SouVoiceAttr member volume using SpuGetVoiceAttr(). 


The value is valid only when the volume mode is "direct mode"; otherwise, it is undefined. 





When the volume mode is not "direct mode", or to get both volume and volume mode at the same time, 
use SpuGetVoiceVolumeAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceVolumeAttr() 
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Basic Sound Library Functions 15-61 


SpuGetVoiceVolumeAttr 


Get volume/volume mode. 





Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceVolumeAttr( 

int voiceNum, Voice Number (0 - 23) 

short *volumeL, Volume (Left) 

short *volumeR, Volume (Right) 

short *volModeL, Volume mode (Left) 

short *volModeR) Volume mode (Right) 

Explanation 


Gets voice volume and volume mode for a voice. Equivalent to getting SpuVoiceAttr members volume and 
volmode using SpuGetVoiceAttr(). 


See also 
SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceVolume() 
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15-62 Basic Sound Library Functions 


SpuGetVoiceVolumeX 

Get current volume. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuGetVoiceVolumeX( 

int voiceNum, Voice Number (0 - 23) 

short *volumeXL, Current volume (Left) 

short *volumeXR) Current volume (Right) 

Explanation 

Gets current volume for a voice. Equivalent to getting SpuVoiceAttr member volumex using 

SpuGetVoiceAttr(). 

See also 


SpuGetVoiceAttr(), SouNGetVoiceAttr(), SouGetVoiceVolume(), SouGetVoiceVolumeAttr() 
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Basic Sound Library Functions 15-63 


Spulnit 

Initialize SPU. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.1 12/14/98 

Syntax 


void Spulnit(voia) 


Explanation 
Initializes SPU. Called only once within the program. After initialization, the state of the SPU is: 


Master volume is O for both L/R 

Reverb is off; reverb work area is not reserved 

Reverb depth and volume are O for both L/R 

Sound buffer transfer mode is DMA transfer 

For all voices: Key off 

For all voices: Pitch LFO, noise, reverb functions not set 
CD input volume is O for both L/R 

External digital input volume is O for both L/R 

DMA transfer initialization set 





The status of the sound buffer is indeterminate after initialization. 


See also 
SpulnitHot(, SouStart)), SpuQuit() 
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15-64 Basic Sound Library Functions 


SpulnitHot 


Initializate SPU (hot reset); preserves sound buffer status. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.1 12/14/98 


Syntax 
void SpulnitHot(void) 


Explanation 

Initializes SPU. Call SpulnitHot() when you initialize the sound system and want to preserve the sound buffer 
status in a child process. 

After initialization, status is the same as Spulnit() except: 


e Voice sample notes not cleared 

e CD volume not cleared 

e Pitch LFO/ noise voice not cleared 

e Voice info (volume, pitch, start address, ADSR) not cleared 


Voices are keyed off, however. 


See also 
Spulnit(, SouStart(), SouQuit() 
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Basic Sound Library Functions 15-65 


SpulnitMalloc 

Initialize sound buffer memory management mechanism. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpulnitMalloc( 

long num, Maximum number of times memory is allocated 

char *top) Pointer to the start address of the memory management table 

Explanation 


Initializes memory management for the sound buffer. You specify n as the maximum number of memory 
blocks that will be allocated, and an area pointed to by top to hold a memory management table, which 
stores information about each block. 


The size of the area pointed to by top must be: 
(SPU_MALLOC_RECSIZ e (num + 1)) bytes 


For example, to allow for 10 SpuMalloc() calls: 


char rec[SPU_MALLOC_RECSIZ * (10 + 1)]; 
SpuInitMalloc (10, /*10 SpuMalloc calls can be made*/ 
rec); /*memory management block*/ 





Return value 
The number of memory management blocks specified. 


See also 
malloc() (See libmath), SouMalloc(), SouMallocWithStartAddr(), SouFree() 
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15-66 Basic Sound Library Functions 


SpulsReverbWorkAreaReserved 


Check if reverb work area is / can be reserved. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpulsReverbWorkAreaReserved( 

long on_off) Contents of the checking process 

Explanation 


Checks to see if the reverb work area corresponding to the current reverb mode is reserved or can be 
reserved, depending on the value of on_off: 


e SPU_DIAG: Using sound buffer memory management mechanism information, SPU_DIAG checks to 
see whether or not the reverb work area is an area allocated by SpuMalloc()/SpuMallocWithStartAdadr(). 
e SPU_CHECK: Checks current reverb work area reserve status. 


Return value 
SPU_ON if the reverb work area is reserved (when on_off is SPU_CHECK) or can be reserved (when on_off 
is SPU_DIAG). 


SPU_OFF if the reverb work area isn’t reserved (when on_off is SPU_CHECk) or can’t be reserved (when 
on_off is SPU_DIAG). 


See also 


SpuReserveReverbWorkArea(), SouSetReverobModeParam(), SouSetReverb(), SouMalloc(, 
SpuMallocWithStartAddr() 
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Basic Sound Library Functions 15-67 


SpulsTransferCompleted 


Check completion of transfer to the sound buffer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpulsTransferCompleted( 

long flag) Check flag 

Explanation 

Checks whether transfer is completed or waits for completion, depending on value of flag: 

SPU_TRANSFER_WAIT Wait until transfer ends 

SPU_TRANSFER_PEEK Check whether transfer has ended and return result 


SPU_TRANSFER_GLANCE Same as SPU_TRANSFER_PEEK 


This function doesn’t work (and returns 1) when a callback function is set with SouSetTransferCallback() 
and started at the completion of DMA transfer. 


Return value 
1 : transfer completed; O : transfer not completed. 


If flag = SPU_TRANSFER_WAIT, waits until transfer ends and always returns 1. If transfer mode is 
SPU_TRANSFER_BY_IO, 1 is returned immediately. 





See also 
SpuWrite(), SpuWritePartly), SouRead(), SouReadDecodedData(), SouSetTransferCalloack() 
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15-68 Basic Sound Library Functions 


SpuLSetVoiceAttr 

Sets attributes for multiple voices. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 4.4 12/14/98 

Syntax 

void SpuLSetVoiceAttr( 

int num Number of elements in argList array 


SpuLVoiceAttr *argList) Address of voice attribute array 


Explanation 
Collectively sets the voice attributes for each individual voice specified in argList. 


Although this function is equivalent to executing SouNSetVoiceAttr() for each voice, processing is faster 
with SpuLSetVoiceAttr(). 


The argList/x].attr. voice specification is ignored and argList/x].attr is set for the voices specified in 
argList[x].voiceNum. 








Set argList[x].attr.mask with bitwise inclusive ORed attributes to specify attributes to be set. When 
argList[x].attr.mask is O, all attributes are set. See Table 15-6 under SpuSetVoiceAttr() for information 
about the attributes that can be set. 





Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-69 


SpuMalloc 

Allocate an area in the sound buffer. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuMalloc( 

long size) Size of area allocated (in bytes) 

Explanation 


Allocate an area of size bytes in the sound buffer. 
Failure occurs if: 


e The requested size cannot be continuously allocated. 
e The only area that satisfies the requested size is part or all of a reverb work area already allocated by 
SpuReserveReverbWorkArea(). 





Return value 
The starting address of the allocated area, if successful; -1 if unsuccessful. 


See also 


SpulnitMalloc(), SouMallocWithStartAddr(), SouFree(), SouSetTransferStartAddr(), SouWrited, 
SpuReserveReverbWorkArea(), SouSetReverb(), SouSetReverbModeParam() 
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15-70 Basic Sound Library Functions 


SpuMallocWithStartAddr 

Allocate an area from an address in sound buffer. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuMallocWithStartAddr( 

u_long adar, Allocated area starting address (in bytes) 

long size) Size of allocated area (in bytes) 

Explanation 


Allocates an area in the sound buffer of size bytes starting from the address adar. (The allocatable area is 
Ox01010 - Ox7ffff.) If adar is in an area already allocated, an area of size bytes is allocated starting from the 
nearest empty area after adar. 





Failure occurs if: 


e The requested size cannot be continuously allocated. 
e The only area that satisfies the requested size is part or all of a reverb work area already allocated by 
SpuReserveReverbWorkArea(). 





Return value 
The starting address of the allocated area, if successful; -1 if unsuccessful. 


See also 


SpulnitMalloc(), SouMalloc(), SouFree(), SouSetTransferStartAddr(), SouWrite(), 
SpuReserveReverbWorkArea(), SouSetReverb(), SouSetReverobModeParam() 
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Basic Sound Library Functions 15-71 


SpuNGetVoiceAttr 


Get voice attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuNGetVoiceAttr( 

int voiceNum, Voice number (0 - 23) 
SpuVoiceAttr *attr) Voice attribute 


Explanation 
Gets attributes for voice voiceNum. All attributes of the attr structure are returned except attr.mask. 


Refer to Table 15-6 under SpuSetVoiceAttr() for details of each attribute. 


See also 

SpuGetVoiceAttr(), SouSetVoiceAttr(), SouNSetVoiceAttr(), SouRSetVoiceAttr(), SouSetKey(), 
SpuSetKeyOnWithAttr), SouGetVoiceVolume(), SouGetVoiceVolumeAttr(), SouGetVoiceVolumex(), 
SpuGetVoicePitch(), SouGetVoiceNote(), SouGetVoiceSampleNote(), SouGetVoiceEnvelope(), 
SpuGetVoiceStartAddr(), SouGetVoiceLoopStartAddr(), SouGetVoiceAR(), SouGetVoiceDR(, 
SpuGetVoiceSR(), SouGetVoiceRR(), SouGetVoiceSL(), SouGetVoiceARAttr(), SouGetVoiceSRAttr(), 
SpuGetVoiceRRAttr(), SouGetVoiceADSR(), SouGetVoiceADSRAttr(), SouGetVoiceEnvelopeAttr() 
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15-72 Basic Sound Library Functions 


SpuNSetVoiceAtir 

Set attributes for a voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuNSetVoiceAttr( 

int voiceNum, Voice number (0 - 23) 

SpuVoiceAttr *attn Voice attribute 

Explanation 


Sets the attributes for a specific voice, specified by voiceNum. 


Specify which attributes are to be set by setting the appropriate bits in attr.mask. (If attr.mask is O, all 
attributes are set.) See Table 15-6 under SpuSetVoiceAttr() for information about specific attributes. 








See also 

SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouRSetVoiceAttr(), SouGetVoiceAttr(), SouNGetVoiceAttr(), 
SpuSetKey(), SouSetKeyOnWithAttr(), SouSetVoiceVolume(), SouSetVoiceVolumeAttr(), SouSetVoicePitch(), 
SpuSetVoiceNote(), SouSetVoiceSampleNote(), SouSetVoiceStartAddr(), SouSetVoiceLoopStartAddr(), 
SpuSetVoiceAR(), SouSetVoiceDR(), SouSetVoiceSR(),SpuSetVoiceRR(), SpuSetVoiceSL(, 
SpuSetVoiceARAttr(), SouSetVoiceSRAttr(), SpuSetVoiceRRAttr(), SouSetVoiceADSR(), 
SpuSetVoiceADSRAttr() 
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Basic Sound Library Functions 15-73 


SpuQuit 
Terminate SPU processing. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

void SpuQuit(voia) 

Explanation 


Terminates SPU processing, and releases events allocated by SPUInit(), so that the maximum number of 
events is not exceeded. This is particularly important when other processes may be calling Spulnit(), such 
as child processes, or in a game that may be part of a demo disk 


See also 
Spulnit(, SoulnitHot() 
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15-74 Basic Sound Library Functions 


SpuRead 

Transfer data from sound buffer to main memory. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuRead( 

u_char “addr, Pointer to transfer data start address in main memory 

u_long size) Transferred data size (in bytes) 

Explanation 


Transfers size bytes of data from the sound buffer to main memory address addr. addr must be a global 
variable or a variable in a heap area that was allocated by a function such as malloc(). It can’t be the 
address of a variable declared on the stack in a function. 








To confirm transfer completion, either call SoulsTransferCompleted() or set the DMA transfer completion 
callback function in advance using SpuSetTransferCallback(). 


Due to the limitations of the DMA transfer hardware, transfers are always performed in 64 byte units. 
Therefore, if the arguments aren’t multiples of 64, it’s possible to damage the data in the SPU memory. 


Return value 
Size of data transferred. (If size is larger than 512 KB, the actual transferred size is returned.) 





See also 
SpuWriteQ, SpuWriteO(), SouWritePartly(), SouSetTransferStartAddr(), SouGetTransferStartAddr(), 
SpulsTransferCompleted(), SouSetTransferCallback() 
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Basic Sound Library Functions 


SpuReadDecodedData 

Transfer sound data decoded by SPU from sound buffer to main memory. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuReadDecodedData( 

SpuDecodedData *d_data, Start address of SpuDecodeData structure in main memory 

long flag) SPU_CDONLY: Set transfer of only CD input 


SPU_VOICEONLY: Set transfer of only Voice 1, 3 
SPU_ALL: Set transfer of all data 
Explanation 
Transfers waveform data decoded by the SPU from the sound buffer to main memory. 
The SPU automatically writes CD input data and Voice 1 and Voice 3 envelope data to the 0x1000-byte 
area at the beginning of the sound buffer, 16 bits at a time at each SPU tick (44.1kHz). Each type of sound 


data has a 0x400 byte buffer, divided into two halves of 0x200 bytes each. The SPU writes one half at a 
time. 


Table 15-2: Arrangement of Data 








Map (bytes) Data Contents 
Ox000 - Ox3ff CD Left channel 
0x200 - Ox’ ff CD Right channel 
0x400 - Oxbff Voice 1 

Ox600 - Oxfff Voice 3 





The main memory address storing the transfer data must be either an address of a global variable or an 
address of an allocated variable in the heap allocated by a function such as malloc(). It may not address a 
stack area (address of an auto variable) declared in a function. 


In order to confirm transfer completion, set the DMA transfer completion callback function in advance using 
SpuSetTransferCallback(). 





Return value 
The buffer area currently being written to; the data that can actually be used is in the other area. 





SPU_DECODE_FIRSTHALF Writes the first half of data 
SPU_DECODE_SECONDHALF Writes the second half of data 
See also 


SpuRead(), SpuWrite(, SouWriteO(), SouWritePartly(), SouSetTransferStartAddr(), 
SpuGetTransferStartAddr(), SoulsTransferCompleted(), SpuSetTransferCallback() 
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15-75 


15-76 Basic Sound Library Functions 


SpuReserveReverbWorkArea 


Reserve/release reverb work area. 





Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

long SpuReserveReverbWorkArea( 

long on_off) Reserve/release flag 

Explanation 


Reserves the current reverb work area corresponding to the current reverb mode, so that it can’t be 
allocated by SpuMalloc()/SpuMallocWithStartAddr(), or releases it so that it can be allocated. 


on_off specifies which action is performed: 


e SPU_ON 
Reserves the reverb work area so that it can’t be allocated by SpuMalloc()/SpuMallocWithStartAddr() 
(without regard to reverb ON/OFF). 
If the area has already been allocated by SpuMalloc() / SouMallocWithStartAdadr(), it is not reserved for 
reverb and SPU_OFF is returned. 


e SPU_OFF 
Releases the reverb work area so that it can be allocated by SpuMalloc() / SouMallocWithStartAddr(). 
Releases it regardless of reverb ON/OFF; reverb must have been turned off beforehand. 





Return value 


The value of on_off, except: if on_off is SPU_ON and the reverb work area has already been allocated by 
SpuMalloc()/SpuMallocWithStartAddr(),SPU_OFF is returned. 


See also 


SpulsReverbWorkAreaReserved(), SouSetReverbModeParam(), SouSetReverb(), SouMalloc(), 
SpuMallocWithStartAddr() 
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Basic Sound Library Functions 15-77 





SpuRGetAllKeysStatus 

Check key on/key off for a range of voices. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.1 12/14/98 

Syntax 

long SpuRGetAllKeysStatus( 

long min, Lower limit of the voice number to be checked 

long max, Upper limit of the voice number to be checked 

char “status) Pointer to the result of checking a voice 

Explanation 


Checks key on/key off and envelope status of all voices in the range min to max. 


status points to an array of 24 bytes, each containing the status value for a voice. See Table 15-1 under 
SpuGetKeyStatus() for a description of possible status values. 


Return value 


SPU_INVALID_ARGS Invalid voice range 
SPU_SUCCESS Keys status contained in status/24]. 
See also 


SpuSetKey(), SouGetKeyStatus() 
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15-78 Basic Sound Library Functions 





SpuRSetVoiceAttr 

Set attributes of a range of voices. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.1 12/14/98 

Syntax 

long SpuRSetVoiceAttr( 

long min, Lower limit of the voice number to be checked 

long max, Upper limit of the voice number to be checked 

SpuVoiceAttr *attn Pointer to voice attributes 

Explanation 





Sets attributes for each voice in the range specified by min and max. You can specify voices within the 
range by setting the bit values SPU_OCH...SPU_28CH in attr.voice. 





Specify which attributes are to be set by setting the appropriate bits in attr.mask. (If attr.mask is O, all 
attributes are set.) See Table 15-6 under SpuSetVoiceAttr() for information about specific attributes. 





Return value 





SPU_INVALID_ARGS Invalid voice range. 
SPU_SUCCESS Voice attributes set for specified range. 
See also 


SpuGetVoiceAttr(), SouSetKey(), SouSetKeyOnWithAttr() 
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Basic Sound Library Functions 15-79 


SpuSetCommonAttir 


Set sound system attributes 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 8/9/99 
Syntax 


void SpuSetCommonAttr( 


SpuCommonaAttr “attr Pointer to attributes common to all voices 


Explanation 


Sets sound system attributes. Specify the attributes (members of attr) by ORing together the terms shown 
below in attr.mask. If attr.mask is O, all attributes are set. 





Table 15-3 





Attribute 


Description 





SPU_COMMON_MVOLL 
SPU_COMMON_MVOLR 
SPU_COMMON_MVOLMODEL 
SPU_COMMON_MVOLMODER 
SPU_COMMON_CDVOLL 
SPU_COMMON_CDVOLR 
SPU_COMMON_CDREV 
SPU_COMMON_CDMIX 
SPU_COMMON_EXTVOLL 
SPU_COMMON_EXTVOLR 
SPU_COMMON_EXTREV 
SPU_COMMON_EXTMIX 


Master volume (left) 

Master volume (right) 

Master volume mode (left) 

Master volume mode (right) 

CD input volume (left) 

CD input volume (right) 

CD input reverb ON/OFF 

CD input ON/OFF 

External digital input volume (left) 
External digital input volume (right) 
External digital input reverb ON/OFF 
External digital input ON/OFF 








The individual parameters that can be set are: 


e Master Volume (attr.mvo/) and Master Volume Mode (attr. mvolmode) 
Left and right are set independently. The volume range obtainable and the various modes are the 
same as the settings for each voice; see Table 15-7 under SpuSetVoiceAttr(). 
e CD Input Volume (attr.cd. volume) 
Set independently for left and right in the range -Ox8000 - Ox7fff. If volume is negative, the phase is 
inverted. 
e CD Input Reverb On/Off (attr.cd. reverb) 
SPU_ON = reverb on; SPU_OFF = reverb off 
e CD Input Mixing On/Off (attr.cd.mix) 
SPU_ON = mixing on; SPU_OFF = mixing off. CD input is not output unless mixing is on. 
e External Digital Inout Volume (attr. ext. volume) 
Set independently for left and right in the range -Ox8000 - Ox7fff. If volume is negative, the phase is 
inverted. 
e External Digital Inout Reverb On/Off (attr. ext. reverb) 
SPU_ON = reverb on; SPU_OFF = reverb off. 
e External Digital Inout Mixing On/Off (attr. ext. mix) 
SPU_ON = mixing on; SPU_OFF = mixing off. External digital inout is not output unless mixing is on. 





See also 
SpuGetCommonAttr(), SouSetVoiceAttr() 
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15-80 Basic Sound Library Functions 


SpuSetCommonCDMix 

Set CD input ON/OFF. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetCommonCDMix( 

long on_off) CD Input on/off 

Explanation 


Turns CD input mixingon/off. Equivalent to the SPU_COMMON_CDMIX SpuSetCommonAttr() mask 
setting. See SouSetCommandaAttr() for values for on_off. 


See also 
SpuSetCommonaAttr(), SouGetCommonCDMix() 
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Basic Sound Library Functions 15-81 


SpuSetCommonCDReverb 

Set CD input reverb ON/OFF. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetCommonCDReverb( 

long on_off) CD Input reverb on/off 

Explanation 


Turns CD input reverb on/off. Equivalent to the SPU_COMMON_CDREV mask setting of 
SpuSetCommonAttr(). SeeSpuSetCommandaAttr() for values for on_off. 


See also 
SpuSetCommonaAttr(), SouGetCommonCDReverb() 
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15-82 Basic Sound Library Functions 


SpuSetCommonCDVolume 
Set CD input volume. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SouSetCommonCDVolume( 

short cdvolL, CD input volume (left) 

short cdvolR) CD input volume (right) 

Explanation 


Sets the CD input volume. Equivalent to the SPU_COMMON_CDVOLL and SPU_COMMON_CDVOLR 
mask settings of SouSetCommonAttr(). See SouSetCommanadAttr() for values for cavolL and cdvolR. 


See also 
SpuSetCommonattr(), SouGetCommonCDVolume() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-83 


SpuSetCommonMasterVolume 


Set master volume. 





Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetCommonMasterVolume( 

short mvolL, Master volume (left) 

short mvoi/R) Master volume (left) 

Explanation 


Sets the master volume. Equivalent to the SPU_COMMON_MVOLL and SPU_COMMON_MVOLR mask 
settings of SouSetCommonAittr(). 





The volume mode is ‘direct mode’ and the range of the values which can be set to the mvolL and mvolR 
volumes is equal to that of the ‘direct mode’ in SpuSetVoiceAttr() (-Ox4000 to Oxfff). 


To set both volume and volume mode simultaneously, use SouSetCommonMasterVolumeAttr(). 
See SpuSetVoiceAttr() for values for mvolL and mvolR. 


See also 


SpuSetCommonaAttr(), SouSetVoiceAttr(), SouSetCommonMasterVolumeAttr(), 
SpuGetCommonMasterVolume(), SouGetCommonMasterVolumeAttr() 
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15-84 Basic Sound Library Functions 


SpuSetCommonMasterVolumeAtir 


Set master volume/master volume mode. 











Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetCommonMasterVolumeAttr( 

short mvolL, Master volume (left) 

short mvoiR, Master volume (left) 

short mvolModeL, Master volume mode (left) 

short mvolModeR) Master volume mode (right) 

Explanation 


Sets the master volume and master volume mode. Equivalent to the SPU_COMMON_MVOLL / 
SPU_COMMON_MVOLR / SPU_LCOMMON_MVOLMODEL / SPU_COMMON_MVOLMODER mask 
settings of SouSetCommonA ttr(). 


See SpuSetVoiceAttr() for values for mvolModeL, mvolModeR, mvolL, and mvolR. 


See also 


SpuSetCommonaAttr(), SouSetVoiceAttr(), SouSetCommonMasterVolume(), 
SpuGetCommonMasterVolume(), SouGetCommonMasterVolumeAttr() 
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SpuSetEnv 


Set basic sound library environment. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuSetEnv( 

SpuEnv “env) Basic sound library environment attribute 
Explanation 


Sets the basic sound library environment. env.mask contains a bit for each attribute (member of env). Set 
the bits of env.mask for the attribute, then set its value in env. When env.mask is O, all attributes are set. 








Currently there is only one attribute, env.queueing, specified by the attribute bit 
SPU_ENV_EVENT_QUEUEING. It establishes whether the following events are queued or not: Key On/Off, 
Pitch LFO Voice Setting, Noise Voice Setting, and Reverb Voice Setting. SPU_ON means the events are 
queued. SPU_OFF means the events are performed immediately (the default value). 











See also 


SpuSetKey(), SouSetKeyOnWithAttr(), SouSetPitchLFOVoice(), SouSetNoiseVoice(), SouSetReverbVoice(), 
SpuFlush(), SouEnv() 
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SpuSetESA 
Set starting address for straight PCM playback 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 4.5 2/24/99 


Syntax 

void SpuSetESA( 

long revAddr) Starting address of SPU memory (local SPU) used for 
PCM playback 


Explanation 

SPU waveform memory can contain compressed ADPCM waveforms, but reverb memory can only contain 
uncompressed (straight) PCM. The SpuSetESA() function is used for playing back these straight PCM 
waveforms. 


Note, however: 


e This function cannot be used together with reverb. 
e §=It is restricted to 22kHz, 16bit, little-endian PCM data. 
e It is currently restricted to monaural, one channel. 


A typical process is as follows: 


1. Initialize the SPU. 

Set reverb mode OFF. 

Use SpuSetESA\() to set the starting address of SPU memory of the PCM data to be played back 
(playback buffer). 

Set the transfer address to the same starting address with SpuSetTransferStartAdadr(). 

Clear the playback buffer. 

Adjust the volume with SetSpuReverobModeDepthi(). 

Use SpuWrite() to transfer PCM data from main memory to the playback buffer. 


on 








NONA 


The value of revAddr depends on the size of the playback buffer in SPU memory that will be used for 
straight PCM playback. Usually the value is Ox80000 minus the buffer size. 


Immediately after the data has been transferred, the buffer data will be played back repeatedly. If it is 
desired to play back a large amount of data that will not fit in the buffer, an SPU interrupt should be used to 
perform double buffering or similar processing. 


The value set with SouSetESA\Q) is valid until the reverb mode changes with a function like 
SpuSetReverbModeParam(). Conversely, it is necessary to call SouSetESA() again whenever the reverb 
move changes. 


See also 
SpuSetTransferStartAddr(), SouWrite(), SouSetReverobModeParam(), SouSetReverbModeDepth() 
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SpuSetiIRQ 

Turn interrupt request ON/OFF. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuSetIRQ( 

long on_off) Sets interrupt request ON/OFF/RESET 

Explanation 


Turns interrupt request ON/OFF. 


Values of on_off can be: 


SPU_ON Set interrupt request 
SPU_OFF Cancel interrupt request 
SPU_RESET Reset interrupt request (cancel current 


interrupt request and reset) 


Return value 
The value that was set (GPU_ON, SPU_OFF, or SPU_RESET). 


See also 
SpuGetIRQ() 
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SpuSetiIRQAddr 


Set interrupt request address. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuSetIRQAdadr( 

u_long addr) Interrupt request address 

Explanation 

Sets interrupt request address value. addr is in bytes, and must be divisible by 8 and less than 512KB. 








The interrupt request occurs when a read/write to the address takes place. 


Return value 

The address that was set. 

If adar is not divisible by 8, it is increased to the next value divisible by 8, and that value is set and returned. 
If the address exceeds 512 KB, O is returned. 


See also 
SpuGetIRQAdadr(), SouSetIRQ(), SpuGetIRQ() 


Run-Time Library Reference CONFIDENTIAL 


Basic Sound Library Functions 15-89 


SpuSetIRQCallback 

Set callback for interrupt request. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

SpuSetIRQCallback( 

SpulRQCallbackProc func) The callback function activated at the time of an interrupt request 

Explanation 


Sets a callback function to be activated when an interrupt request occurs. If func is set to NULL, the 
callback is cleared. 


Return value 
Pointer to the previously set callback function. 


See also 
SpuSetIRQ(), SpuSetIRQAdadr() 
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SpuSetKey 

Set key on/key off for each voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

void SpuSetKey( 

long on_off, Sets key on/key off 

u_long voice_bit) Set voice 

Explanation 


Sets key on/key off value for each voice specified by voice_bit. (GPU_ON = key on; SPU_OFF = key off) 


Set voice_bit by ORing together the bits for each voice (GPU_OCH, SPU_1CH...SPU_23CH). For example, 
to set key on for voice O and voice 2: 


SpuSetKey (SPU_ON, /* set key on */ 
SPU_OCH | SPU_2CH); /* 0 ch and 2 ch */ 


See also 
SpuSetKeyOnWithAttr(), SouSetVoiceAttr() 
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SpuSetKeyOnWithAttr 

Set key on with attributes. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

void SpuSetKeyOnWithAttir( 

SpuVoiceAttr “attr Pointer to voice attributes 

Explanation 


Specifies attributes for each voice and sets key on. 


Explicitly specify the voices to be produced by ORing together the appropriate bits (GPU_OCH, 
SPU_1CH...SPU_23CH) in attr.voice. 


Specify the attributes to be set by ORing together the appropriate bits in attr. mask and setting the 
corresponding values of attr. (If attr.mask is O, all attributes are set.) See SpuSetVoiceAttr() (Table 15-6) for 
a list of the attributes and their descriptions. 








See also 
SpuSetKey(), SouSetVoiceAttr(), SouGetVoiceAttr(), SouVoiceAttr() 
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SpuSetMute 
Turn sound muting ON/OFF. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 
long SpuSetMute( 
long on_off) Mute ON/OFF 


Explanation 
Turns sound muting ON/OFF. SPU_ON = Mute on; SPU_OFF = mute off. 


Note: CD input and external digital inout are not affected. 


Return value 
The value set. 


See also 
SpuGetMute() 
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SpuSetNoiseClock 


Set noise source clock. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 

long SpuSetNoiseClock( 

long n_clock) Noise source clock 
Explanation 


Sets noise source clock to n_clock. The value must be in the range 0-Ox3f. It is applied to all voices for 
whom the noise source is set with SouSetNoiseVoice(). 





Return value 
The noise source clock value set. 


See also 
SpuGetNoiseClock(), SouSetNoiseVoice(), SouGetNoiseVoice() 
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SpuSetNoiseVoice 

Turn noise source ON/OFF for each voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuSetNoiseVoice( 

long on_off, Sets noise source ON (SPU_ON), OFF (SPU_OFF), or direct bit pattern 

(SPU_BIT) 
u_long voice_bit) Set voice 
Explanation 


Turns noise source on or off for specific voices. Any number of voices may be specified in voice_bit by 
setting the bit values SPU_OCH...SPU_23CH. 


on_off can have the following settings: 





SPU_ON Noise source turned on for voices whose bits in voice_bit are 1 
SPU_OFF Noise source turned off for voices whose bits in voice_bit are 1 
SPU_BIT Noise source turned on for voices whose bits in voice_bit are 1, 


and turned off for voices whose bits are O 








SpuSetNoiseVoice (SPU_ON, /*set noise source on*/ 
SPU_OCH | SPU_2CH); /*0 ch and 2 ch*/ 


Return value 


An unsigned long whose low 24 bits show the current noise source on/off value for each voice (after 
setting). To check any voice, AND with the appropriate mask SPU_OCH...SPU_23CH. 


See also 
SpuSetNoiseClock(), SouGetNoiseClock(), SouGetNoiseVoice() 
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SpuSetPitchLFOVoice 
Set pitch LFO ON/OFF for each voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Syntax 
u_long SpuSetPitchLFOVoice( 
long on_off, SPU_ON: Sets pitch LFO on 
SPU_OFF: Sets pitch LFO off 
SPU_ BIT: Sets direct bit pattern 
u_long voice_bit) Set voice 
Explanation 


Turns pitch LFO on or off for specific voices. Any number of voices may be specified in voice_bit by setting 
the bit values SPU_OCH...SPU_23CH. 


When pitch LFO is on, voice n is set so that LFO sets pitch when the volume of voice (n-1) undergoes a 
time change. To allow pitch LFO, voice n and voice (n-1) must be started. Voice (n - 1) can produce sound 
at an optional timing after voice n starts; LFO is applied at the moment when voice (n-1) starts playback. 





on_off can have the following settings: 


SPU_ON Pitch LFO turned on for voices whose bits in voice_bit are 1 
SPU_OFF Pitch LFO turned off for voices whose bits in voice_bit are 1 
SPU_BIT Pitch LFO turned on for voices whose bits in voice_bit are 1, and 





turned off for voices whose bits are O 


Return value 


An unsigned long whose low 24 bits show the current pitch LFO on/off value for each voice (after setting). 
To check any voice, AND with the appropriate mask SPU_OCH...SPU_23CH. 


See also 
SpuGetPitchLFOVoice(), SouSetKey(), SouSetKeyOnWithAttr() 
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SpuSetReverb 
Turn reverb ON/OFF. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Syntax 
long SpuSetReverb( 
long on_off) SPU_ON: Set reverb on 
SPU_OFF: Set reverb off 
Explanation 


Turns reverb on or off. 


If on_off is SPU_OFF, if a reverb work area was not reserved with SouReserveReverbWorkArea(), this 
function checks whether the area is available (i.e. not allocated by SpuMalloc(). If it is available, reverb is 
turned on and SPU_ON is returned. If not, reverb is turned off and SPU_OFF is returned. If it is not being 


Return value 
The reverb on/off value (SPU_ON or SPU_OFF) 


See also 
SpuGetReverb(), SouSetReverbModeParam(), SouReserveReverbWorkArea() 
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SpuSetReverbDepth 

Set the reverb depth parameter. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuSetReverbDepth( 

SpuReverbAttr *attr) Pointer to reverb attribute 

Explanation 


Sets the reverb depth parameter attribute. It is set independently for left and right, by setting the 
appropriate bits (GPU_REV_DEPTHL for left, SPU_REV_DEPTHR for right) of attr.mask. (If attr.mask is O, 
left and right attributes are set simultaneously.) 


The range for reverb depth is -Ox8000 to Ox’7fff. If the value is negative, the reverb sound (wet) phase is 
inverted. 


Return value 
0. 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam() 
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SpuSetReverbModeDelayTime 


Set reverb delay time. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetReverbModeDelayTime( 

long delay) Reverb delay time 

Explanation 


Sets the reverb delay time, in the range 0-127. Equivalent to the SPU_REV_DELAYTIME mask setting of 
SpuSetReverbModeParam(). 


Delay time is effective only with reverb modes SPU_LREV_MODE_ECHO or SPU_LREV_MODE_DELAY. 
There is no effect if any other mode is set. 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam(), SouGetReverbModeDelayTime() 
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SpuSetReverbModeDepth 


Set reverb mode depth. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetReverbModeDepth( 

short depthL, reverb depth (left) 

short depthR) reverb depth (right) 

Explanation 


Sets the reverb depth. Values are set independently for left and right, in the range -Ox8000 to Ox7fff. If the 
value is negative, the reverb sound (wet) phase is inverted. Equivalent to the SPU_REV_DEPTHL and 
SPU_REV_DEPTHR mask settings of SouSetReverbModeParam(). 





See also 


SpuSetReverbModeParam(), SouGetReverobModeParam(), SouGetReverobModeDepthi(), 
SpuSetReverbDepth() 


CONFIDENTIAL Run-Time Library Reference 


15-100 Basic Sound Library Functions 


SpuSetReverbModeFeedback 


Set reverb feedback. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.7 12/14/98 

Syntax 

void SpuSetReverbModeFeedback( 

long feedback) Reverb feedback 

Explanation 


Sets the reverb feedback. Values can be 0-127. Equivalent to the SPU_REV_FEEDBACK mask setting of 
SpuSetReverbModeParam(). 


Feedback is effective only with reverb modes SPU_REV_MODE_ECHO or SPU_REV_MODE_DELAY. There 
is no effect with any other mode. 


See also 
SpuSetReverbModeParam(), SouGetReverbModeParam(), SouGetReverbModeFeedback() 
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SpuSetReverbModeParam 


Set reverb mode and attributes. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

long SpuSetReverbModeParam( 

SpuReverbAttr “attr Pointer to reverb attributes 

Explanation 


Sets reverb mode and attributes. 


You can specify the attributes (members of attr) to be set by ORing together the appropriate bits of 
attr.mask (see Table 15-4). If attr.mask is O, all attributes are set. 





Table 15-4 Reverb attributes 








Attribute Description 

SPU_REV_MODE Mode setting 
SPU_REV_DEPTHL Reverb depth (left) 
SPU_REV_DEPTHR Reverb depth (right) 
SPU_REV_DELAYTIME Delay time (ECHO, DELAY only) 
SPU_REV_FEEDBACK Feedback (ECHO, DELAY only) 





e Reverb Mode (attr.mode) 
When reverb mode is changed (which happens even at initial setting, because the initial value is 
SPU_REV_MODE_OFF), the internal reverb depth value is O even if depth was previously set by 
SpuSetReverbModeParam(). This is because the work area size changes when this mode changes, so 
incorrect data in the work area produces noise. So after the reverb mode changes, depth needs to be 
reset using SouSetReverbModeParam() or SpuSetReverbDepth(). 








Based on reverb characteristics, the time to complete one scan of the work area is estimated and the 
mode/depth are set; or, after the mode is set, the work area data is erased, then depth is set. 








The size the work area depends on the reverb mode as shown below. However, this area is managed 
by a memory management mechanism such as SpuMalloc(). See SpuMalloc() for details. 


Table 15-5: Sound Buffer Work Area Size for Reverb Modes 








attr. mode mode hexadecimal decimal 
SPU_REV_MODE_OFF off 0/80* 0/128* 
SPU_REV_MODE_ROOM room 26c0 9920 
SPU_REV_MODE_STUDIO_A studio (small) 140 8000 
SPU_REV_MODE_STUDIO_B studio (med) 4840 18496 
SPU_REV_MODE_STUDIO_C _ studio (big) 6feO 28640 
SPU_REV_MODE_HALL hall adeO 44512 
SPU_REV_MODE_SPACE space echo f6cO 63168 
SPU_REV_MODE_ECHO echo 18040 98368 
SPU_REV_MODE_DELAY delay 18040 98368 
SPU_REV_MODE_PIPE half echo 3c00 15360 





*Note: 128 bytes if SouReserveReverbWorkArea (SPU_ON) is used for address setting, even if the 
mode is off; O bytes otherwise. 

If SPU_REV_MODE_CLEAR_WA is set in attr.mode, the reverb work area is cleared, as a measure 
against noise when changing modes. Since the sound buffer is cleared by synchronous DMA transfer, 
other processing (drawing, sound generation) is blocked during this process. 


SpuClearReverbWorkArea() can also be used to clear the work area. 
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e Reverb Depth (attr. depth) 
Values are set independently for left and right, in the range -Ox8000 to Ox7fff. If the value is negative, 
the reverb sound (wet) phase is inverted. 

e Delay Time (atir.delay) 
Values are in the range 0-127. Valid only when mode is SPU_LREV_MODE_ECHO or 
SPU_REV_MODE_DELAY. 

e Feedback (attr.feedback) 
Values are from O to 127. Valid only when mode is SPU_LREV_MODE_ECHO or 
SPU_REV_MODE_DELAY. 











Return value 

If the area needed as a work area by the new mode was allocated for another area SpuMalloc()/ 
SpuMallocWithStartAddr(), none of the set reverb attributes are set and SPU_ERROR is returned. If it is not 
being used, the set reverb attributes are set and O is returned. 


SPU_ERROR is also returned when an invalid SPU_REV_MODE is set. 








See also 
SpuGetReverbModeParam(), SpuMalloc(), SouMallocWithStartAddr(), SouReserveReverbWorkArea(), 
SpuClearReverbWorkArea() 
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SpuSetReverbModeType 

Set reverb mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h OT 12/14/98 

Syntax 

void SpuSetReverbModeType( 

long type) Reverb mode type 

Explanation 


Sets the reverb mode. Equivalent to the SPU_REV_MODE mask setting of SouSetReverbModeParam(). 





See Table 15-5 under SpuSetReverbModeParam() for the possible values of type. 





See also 


SpuSetReverbModeParam(), SouGetReverbModeParam(), SpuMalloc(), SouMallocWithStartAddr(), 
SpuReserveReverbWorkArea(), SouClearReverbWorkArea(), SouGetReverobModeType() 
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SpuSetReverbVoice 

Set reverb ON/OFF for each voice. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuSetReverbVoice( 

long on_off, Sets reverb ON (SPU_ON), OFF (SPU_OFF), or direct bit pattern 

(SPU_BIT) 
u_long voice_bit) Set voice 
Explanation 


Turns reverb on or off for specific voices. Any number of voices may be specified in voice_bit by setting the 
bit values SPU_OCH...SPU_28CH. 


on_off can have the following settings: 


SPU_ON Reverb turned on for voices whose bits in voice_bit are 1 
SPU_OFF Reverb turned off for voices whose bits in voice_bit are 1 
SPU_BIT Reverb turned on for voices whose bits in voice_bit are 1, and turned off for 





voices whose bits are O 


For example, to set voice O and voice 2 reverb on: 





SpuSetReverbVoice(SPU_ON, /*set reverb on*/ 
SPU_OCH | SPU_2CH); /*0 ch and 2 ch*/ 


Return value 


An unsigned long whose low 24 bits show the current noise source on/off value for each voice (after 
setting). To check any voice, AND with the appropriate mask SPU_OCH...SPU_23CH. 





See also 
SpuGetReverbVoice() 
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SpuSetTransferCallback 


Set callback function for completion of DMA transfer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.1 12/14/98 
Structure 
SpuTransferCallbackProc SpuSetTransferCallback( 
SpuTransferCallbackProc func) Callback function for completion of DMA 
transfer. 
Explanation 


Sets function to be called when DMA transfer is completed. If func is NULL, the callback is cleared. 





When a callback set by this function executes at DMA transfer completion, SoulsTransferCompleted() does 
not function. 


Return value 
The previously set callback function. If no callback function was set, NULL is returned. 


See also 


SpuWrite(), SouWriteO(), SouWritePartly(), SouRead(), SouReadDecodedData(), SouSetTransferMode(, 
SpuGetTransferMode(), SoulsTransferCompleted() 
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SpuSetTransferMode 

Set sound buffer transfer mode. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

long SpuSetTransferMode( 

long mode) Mode: see table below 

Explanation 


Sets the mode for transferring data from main memory to the sound buffer. The mode values can be: 


e SPU_TRANSFER_BY_DMA: DMA transfer; can do other processing during transfer (default value). 
SPU_TRANSFER_BY_IO: I/O transfer. Uses CPU; cannot do other processing during transfer. 


Note: These specifications are valid only when transferring data from main memory to the sound buffer. 
DMA transfer is always used when transferring data from the sound buffer to main memory. 


When a transfer is done without first calling this function, the transfer mode is the previously set value. 


Return value 
The transfer mode set (GPU_TRANSFER_BY_DMA of SPU_TRANSFER_BY_IO) 





See also 
SpuGetTransferMode(), SpuWrite(), SouWriteO(), SouWritePartly(). 
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SpuSetTransferStartAddr 


Set sound buffer transfer start address. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 
Syntax 
u_long SpuSetTransferStartAddr( 
u_long addr) Sound buffer transfer destination/transfer source start address 
Explanation 


Sets a starting address in the sound buffer, specified in adar, for transferring data to and from main 
memory. addr must be a byte value that is 





e Divisible by 8. If it is not divisible by 8, it is increased to the next value divisible by 8. 
e Between 0x1010 - Ox7ffff for transfers to the sound buffer. 
e Between O - OxOfff for transfers from the sound buffer. See SouReadDecodedData\(). 


Note: 0x1000 - 0x100f is reserved for the system. 


Return value 
Start address value. If the address specified is smaller than 0x1010 or greater than 512 KB, O is returned. 


See also 
SpuGetTransferStartAddr(), SouWrite), SouWriteO(), SouWritePartly), SouRead(), SouReadDecodedData() 
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SpuSetVoiceADSR 

Set ADSR values. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceADSR( 

int voiceNum, Voice number (0 - 23) 

u_short AR, ADSR attack rate 

u_short DR, ADSR decay rate 

u_short SR, ADSR sustain rate 

u_short RRP, ADSR release rate 

u_short SL) ADSR sustain level 

Explanation 


Sets individual ADSR attributes for a voice. Corresponds to SpuSetVoiceAttr() mask specifications 
SPU_VOICE_ADSR_AR / SPU_VOICE_ADSR_DR / SPU_VOICE_ADSR_SR / SPU_VOICE_ADSR_RR / 
SPU_VOICE_ADSR_SL. 


The rate modes used are: 


Attack Rate: SPU_VOICE_LINEARIncN (Linear Increase) 
Sustain Rate: SPU_VOICE_LINEARDecN (Linear Decrease) 
Release Rate: SPU_VOICE_LINEARDecN (Linear Decrease) 


See Table 15-10 under SpuSetVoiceAttr() for values that can be specified for each rate. To set multiple rate 
modes at the same time, use SouSetVoiceADSRAttr(). 





See also 


SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceAR(), SouSetVoiceDR(), SouSetVoiceSR(), 
SpuSetVoiceRR(), SouSetVoiceSL() 
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SpuSetVoiceADSRAttr 

Set ADSR and ADSR modes. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 8/9/99 

Syntax 

void SpuSetVoiceADSRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short AR, ADSR attack rate 

u_short DR, ADSR decay rate 

u_short SR, ADSR sustain rate 

u_short RR, ADSR release rate 

u_short SL, ADSR sustain level 

long ARmode, ADSR attack rate mode 

long SRmode, ADSR sustain rate mode 

long RRmode) ADSR release rate mode 

Explanation 


Sets ADSR attributes and mode. Corresponds to SpuSetVoiceAttr() mask specifications 
SPU_VOICE_ADSR_AR / SPU_VOICE_ADSR_DR / SPU_VOICE_ADSR_SR / SPU_VOICE_ADSR_RR / 
SPU_VOICE_ADSR_SL /SPU_VOICE_ADSR_AMODE / SPU_VOICE_ADSR_SMODE / 
SPU_VOICE_ADSR_RMODE. 


Refer to SouSetVoiceAttr() for values that can be specified in each rate and rate mode. 


See also 


SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceADSR(), SouSetVoiceAR(), SouSetVoiceDR(), 
SpuSetVoiceSR(), SouSetVoiceRR(), SpuSetVoiceSL(), SouSetVoiceARAttr(), SouSetVoiceSRAttr(), 
SpuSetVoiceRRAttr() 
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SpuSetVoiceAR 
Set ADSR attack rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuSetVoiceAR( 

int voiceNum, Voice number (0 - 23) 
u_short AR) ADSR attack rate 


Explanation 
Sets ADSR attack rate for a voice. Corresponds to SpuSetVoiceAttr() mask specification 
SPU_VOICE_ADSR_AR. 


ADSR attack rate mode becomes SPU_VOICE_LINEARIncN (Linear increase mode). To set ADSR attack 
rate and ADSR attack rate mode at the same time, use SpuSetVoiceARAttr(). 








Refer to SpuSetVoiceAttr() for values that can be specified in AR. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceARAttr() 
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SpuSetVoiceARAttr 

Set ADSR attack rate / attack rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceARAttr( 

int voiceNum, Voice number (0 - 23) 

u_short AR, ADSR attack rate 

long Armode) ADSR attack rate mode 

Explanation 


Sets ADSR attack rate / ADSR attack rate mode for a voice. Corresponds to SpuSetVoiceAttr() mask 
specifications SPU_VOICE_ADSR_AR and SPU_VOICE_ADSR_AMODE. Refer to SouSetVoiceAttr() for 
values that can be specified in AR and ARmode. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceAR\() 
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SpuSetVoiceAttr 


Set attributes for each voice. 


Library Header File Introduced 
libspu. lib libspu.h 3.0 
Syntax 


void SpuSetVoiceAttr( 


SpuVoiceAttr *attr) Pointer to voice attributes 


Explanation 
Sets attributes for one or more voices. 





Documentation Date 
12/14/98 


To specify the voices whose attributes you wish to set, OR together the appropriate bits of attr. voice 





(SPU_OCH...SPU_23CH). 


To specify which attributes to set, OR together the terms shown below in attr.mask, then set the values of 


the corresponding members of attr. (If attr.mask is O, all attributes are set.) 


Table 15-6 Voice Attributes 











Attribute value for attr. mask Description Member of attr to set 
SPU_VOICE_VOLL Volume (left) volume 
SPU_VOICE_VOLR Volume (right) volume 
SPU_VOICE_VOLMODEL Volume mode (left) volmode 
SPU_VOICE_VOLMODER Volume mode (right) volmode 
SPU_VOICE_PITCH Interval (pitch specification) pitch 
SPU_VOICE_NOTE Interval (note specification) note 
SPU_VOICE_SAMPLE_NOTE Waveform data sample note sample_note 
SPU_VOICE_WDSA Waveform data start address addr 
SPU_VOICE_ADSR_AMODE ADSR Attack rate mode a_mode 
SPU_VOICE_ADSR_SMODE ADSR Sustain rate mode s_mode 
SPU_VOICE_ADSR_RMODE ADSR Release rate mode r_mode 
SPU_VOICE_ADSR_AR ADSR Attack rate ar 
SPU_VOICE_ADSR_DR ADSR Decay rate dr 
SPU_VOICE_ADSR_SR ADSR Sustain rate sr 
SPU_VOICE_ADSR_RR ADSR Release rate rr 
SPU_VOICE_ADSR_SL ADSR Sustain level sl 
SPU_VOICE_ADSR_ADSR1 ADSR adsr1 for 'VagAtr' adsr1 
SPU_VOICE_ADSR_ADSR2 ADSR adsr2 for 'VagAtr' adsr2 
SPU_VOICE_LSAX Loop start address loop_addr 





The individual settings are described below. 


e Volume and Volume Mode 


The volume modes and their range of possible volume settings are shown below: 


Table 15-7: Volume Mode and Volume Setting Ranges 





Mode (phase) 


SPU_VOICE_VOLMODEx 


SPU_VOICE_VOLx 





Direct mode 
Linear inc. mode 
Linear inc. mode 
Linear dec. mode 
Linear dec. mode 
Expon. inc. mode 
Expon. inc. mode 
Expon. dec. mode 


SPU_VOICE_DIRECT 
SPU_VOICE_LINEARIncN 
SPU_VOICE_LINEARIncR 
SPU_VOICE_LINEARDecN 
SPU_VOICE_LINEARDecR 
SPU_VOICE_EXPIncN 
SPU_VOICE_EXPIncR 
SPU_VOICE_EXPDec 


-Ox4000 - OxSfff 
0x00 - Ox7f (normal) 
0x00 - Ox7f (inverted) 
Ox00 - Ox7f (normal) 
0x00 - Ox7f (inverted) 
Ox00 - Ox7f (normal) 
Ox00 - Ox7f (inverted) 
Ox00 - Ox7f 
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Direct Mode 

Specifies a fixed volume (the default mode). When the volume is negative, its phase is inverted. 

Linear Increase Mode (Normal Phase) 

When the current volume value is positive, volume increases linearly from the current value to the 
maximum value. 

Linear Increase Mode (Inverted Phase) 

When the current volume value is negative (inverted phase), volume increases linearly from the current 
value to the maximum value, with phase inverted. 

Linear Decrease Mode (Normal Phase) 

When the current volume value is positive, volume decreases linearly from the current value to the 
minimum volume value. 

Linear Decrease Mode (Inverted Phase) 

When the current volume value is negative (inverted phase), volume decreases linearly from the current 
value to the minimum volume value, with phase inverted. 

Exponential Increase Mode (Normal Phase) 

When the current volume value is positive, volume increases exponentially from the current value to the 
maximum value. 

Exponential Increase Mode (Inverted Phase) 

When the current volume value is negative (inverted phase), volume increases exponentially from the 
current value to the maximum value, with phase inverted. 

Exponential Decrease Mode 

Whether the current volume value is positive or negative, volume decreases exponentially from the 
current value to the minimum volume value. 






























































Playback rate (set pitch, set note) 
May be set by the two methods listed below: 





Pitch specification: specifies an interval in attr.pitch in the range 0x0000-0Ox3fff. 


Table 15-8: Pitch Specification Values and Interval 


2. 





Value Set 
Interval 


Ox0200 
- 3 oct. 


Ox0400 
- 2 oct. 


Ox0800 
- 1 oct. 


0x1000 
tone 


0x2000 
+1 oct. 


OxSfff 
+2 oct. 



































Note specification: specifies an interval in attr.note as follows, using a 16-bit value for note and cent 
(here, the value of a half tone divided by 128). 


Table 15-9: Note/Sample Note Specification Values 








Bit Value Set 
Upper 8 bits MIDI note number 
Lower 8 bits Cent (expressed as a half tone divided by 


128) 











This setting cannot be used unless the waveform data sample note feature, described below, is set. 


Waveform Data Sample Note 

Sets interval in attr.sample_note at the time of sampling, using a 16-bit value for note and cent, as 
shown in Table 15-9. Setting this value makes it possible to set the playback rate as above. 
Waveform Data Start Address 

attr.add specifies the sound buffer starting address of the waveform data you want to produce in the 
voice. 

Loop Start Address 

If waveform data that generates sound in a voice is created with a loop specified, and if the waveform 
starting address is set, it is unnecessary to set the loop start address explicitly. 

However, when you wish to set a loop start address dynamically at the time of execution, you must set 
attr.loop_addr to the start address of the loop in the sound buffer. 

If a loop was not set at the time of waveform data creation, even if SPU_VOICE_LSAX is specified and 
set in attr.loop_addr, that setting is invalid. 
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e ADSR 
A conceptual diagram of ADSR is shown below. 
Figure 15-1: ADSR Conceptual Diagram 


A 
Volume 


Sustain |_ 
Level 














key on key off time 
The attributes that can be set and their ranges are shown in Table 15-10. 


Table 15-10: Rate and Level Setting Ranges 








Attribute Structure Member Setting Range 
Attack rate attr.ar 0x00 - Ox7f 
Decay rate attr.dr OxO - Oxf 
Sustain rate attr.sr Ox00 - Ox7f 
Release rate attr.rr Ox00 - Oxf 
Sustain level attr.sl 0x0 - Oxf 





Rate curves may be set for Attack, Sustain, Release (see Table 15-11). Because only exponential 
decrease may be used for Decay, that attribute cannot be set. 








Table 15-11: ADSR Rate Modes 








Attribute Settable modes 

Attack rate SPU_VOICE_LINEARIneN (linear increase ) 
(attr.a_mode) SPU_VOICE_EXPIncN (exponential increase) 
Sustain rate SPU_VOICE_LINEARIneN (linear increase ) 
(attr.s_mode) SPU_VOICE_LINEARDecN (linear decrease) 





SPU_VOICE_EXPIncN (exponential increase) 

SPU_VOICE_EXPDec (exponential decrease) 
Release rate SPU_VOICE_LINEARDecN (linear decrease) 
(attr.r_mode) SPU_VOICE_EXPDec (exponential decrease) 











Also, data from structure VagAtr members adsr7 and adsr2 may be set directly in attr.adsr7 and attr.adsr2. 
In this case only SPU_VOICE_ADSR_ADSR1 and SPU_VOICE_ADSR_ADSR2 can be set for ADSR in 
attr.mask. 


See also 
SpuRSetVoiceAttr(), SouGetVoiceAttr(), SouSetKey(), SouSetKeyOnWithAttr(), SpuVoiceAttr(). 
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SpuSetVoiceDR 
Set ADSR decay rate. 


Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceDR( 

int voiceNum, Voice number (0 - 23) 

u_short DR) ADSR decay rate 

Explanation 


Sets ADSR decay rate used in voice voicenum. Corresponds to SpuSetVoiceAttr() mask specification 
SPU_VOICE_ADSR_DR. Refer to SpuSetVoiceAttr() for values that can be specified in DR. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr() 
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SpuSetVoiceLoopStartAddr 


Set loop start address of waveform data in sound buffer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceLoopStartAddr( 

int voiceNum, Voice number (0 - 23) 

u_long /oopStartAdar) Loop start address 

Explanation 


Sets start address of waveform data in the sound buffer. Corresponds to SpuSetVoiceAttr() mask 
specification SPU_VOICE_LSAX. See SpuSetVoiceAttr() for values that can be specified in loopStartAdar. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetTransferStartAddr(). 
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SpuSetVoiceNote 

Set interval (note specification). 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceNote( 

int voiceNum, Voice number (0 - 23) 

u_short note) Interval (note specification) 

Explanation 


Sets the voice interval by note. Corresponds to SpuSetVoiceAttr() mask specification SPU_VOICE_NOTE. 


Refer to SouSetVoiceAttr() for values that can be specified in the interval by note specification. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceSampleNote() 
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SpuSetVoicePitch 

Set interval (pitch specification). 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoicePitch( 

int voiceNum, Voice number (0 - 23) 

u_short pitch) Interval (pitch specification) 

Explanation 


Sets the voice interval by pitch. Corresponds to SpuSetVoiceAttr() mask specification SPU_VOICE_PITCH. 
Refer to SouSetVoiceAttr() for values that can be specified in the interval by pitch specification. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr() 
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SpuSetVoiceRR 
Set ADSR release rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuSetVoiceRR( 

int voiceNum, Voice number (0 - 23) 
u_short RR) ADSR release rate 


Explanation 
Sets ADSR release rate for for voice voiceNum. Corresponds to SpuSetVoiceAttr() mask specification 
SPU_VOICE_ADSR_RR. 


ADSR release rate mode becomes SPU_VOICE_LINEARDecN (Linear decrease mode). To set release rate 
and release rate mode at the same time, use SpuSetVoiceRRAttr. 








Refer to SpuSetVoiceAttr() for values that can be specified in RR. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceRRAttr() 
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SpuSetVoiceRRAttr 

Set ADSR release rate / release rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceRRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short RR, ADSR release rate 

long RRmode) ADSR release rate mode 

Explanation 





Sets ADSR release rate / ADSR release rate mode for voice voiceNum. Corresponds to SpuSetVoiceAttr() 
mask specifications SPU_VOICE_ADSR_RR and SPU_VOICE_ADSR_RRMODE. 


Refer to SpuSetVoiceAttr() for values that can be specified in RR and RRmode. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceRR() 
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SpuSetVoiceSampleNote 


Set waveform data sample note. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceSampleNote( 

int voiceNum, Voice number (0 - 23) 

u_short sampleNote) Sets waveform data sample note 

Explanation 


Sets the waveform data sample note for voice voiceNum. Corresponds to SpuSetVoiceAtir() mask 
specification SPU_VOICE_SAMPLE_NOTE. Refer to SouSetVoiceAttr() for values that can be specified in 
sampleNote. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceNote() 
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SpuSetVoiceSL 
Set ADSR sustain level. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuSetVoiceSL( 

int voiceNum, Voice number (0 - 23) 
u_short SL) ADSR sustain level 
Explanation 


Sets ADSR sustain level used for voice voiceNum. Corresponds to SpuSetVoiceAttr() mask specification 
SPU_VOICE_ADSR_SL. 


ADSR sustain level mode becomes SPU_VOICE_LINEARDecN (Linear decrease mode). To set ADSR 
sustain level and ADSR sustain level mode at the same time, use SpuSetVoiceAttr(). 








Refer to SpuSetVoiceAttr() for values that can be specified in SL. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceRRAttr() 
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SpuSetVoiceSR 
Set ADSR sustain rate. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 


Syntax 

void SpuSetVoiceSR( 

int voiceNum, Voice number (0 - 23) 
u_short SR) ADSR sustain rate 


Explanation 
Sets ADSR sustain rate used for voice voiceNum. Corresponds to SpuSetVoiceAttr() mask specification 
SPU_VOICE_ADSR_SR. 


ADSR sustain rate mode becomes SPU_VOICE_LINEARDecN (Linear decrease mode). To set ADSR 
sustain rate and ADSR sustain rate mode at the same time, use SpuSetVoiceSRAttr(). 





Refer to SpuSetVoiceAttr() for values that can be specified in SR. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceSRAttr() 
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SpuSetVoiceSRAttr 

Set ADSR sustain rate / sustain rate mode. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceSRAttr( 

int voiceNum, Voice number (0 - 23) 

u_short SR, ADSR sustain rate 

long SRmode) ADSR sustain rate mode 

Explanation 


Sets ADSR sustain rate / ADSR sustain rate mode used for voice voiceNum. Corresponds to 
SpuSetVoiceAttr() mask specifications SPU_VOICE_ADSR_SR and SPU_VOICE_ADSR_SRMODE. Refer to 
SpuSetVoiceAttr() for values that can be specified in SR and SRmode. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceSR() 
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SpuSetVoiceStartAddr 

Set start address of waveform data in sound buffer. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceStartAddr( 

int voiceNum, Voice number (0 - 23) 

u_long startAddr) Waveform data start address 

Explanation 


Sets start address of waveform data in the sound buffer. Corresponds to SpuSetVoiceAttr() mask 
specification SPU_VOICE_WDSA. See SpuSetTransferStartAddr() for allowable values of startAdar. 





See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetTransferStartAddr() 
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SpuSetVoiceVolume 

Set voice volume. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceVolume( 

int voiceNum, Voice Number (0 - 23) 

short volumeL, Volume (Left) 

short volume) Volume (Right) 

Explanation 


Sets the voice volume. Corresponds to SpuSetVoiceAttr() mask specifications SPU_VOICE_VOLL and 
SPU_VOICE_VOLR 


Volume mode becomes "Direct Mode", and the range of values that can be specified in volumeL and 
volumeR is equivalent to "Direct Mode" of SpuSetVoiceAttr(). To specify both volume and volume mode at 
the same time, use SpuSetVoiceVolumeAttr(). See SouSetVoiceAttr() for values that can be specified in 
volumeL and/or volumeR. 





See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceVolumeAttr() 
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SpuSetVoiceVolumeAtir 


Set voice volume/volume mode. 





Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.6 12/14/98 

Syntax 

void SpuSetVoiceVolumeAttr( 

int voiceNum, Voice Number (0 - 23) 

short volumeL, Volume (Left) 

short volumeR, Volume (Right) 

short volModeL, Volume mode (Left) 

short volModeR) Volume mode (Right) 

Explanation 


Sets voice volume and/or volume mode. Corresponds to SpuSetVoiceAttr() mask specifications 
SPU_VOICE_VOLL / SPU_VOICE_VOLR / SPU_VOICE_VOLMODEL / SPU_VOICE_VOLMODER. 


See SpuSetVoiceAttr() for values that can be specified in volVodeL, volModeR, volumeL and/or volumeR. 


See also 
SpuSetVoiceAttr(), SouNSetVoiceAttr(), SouSetVoiceVolumeAttr() 
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SpuStart 
Start SPU processing. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 
void SpuStart(void) 


Explanation 


Starts SPU processing. This function is also called by Spulnit(), so it is not necessary to call it when 
initializing, but SpuStart() must be called after calling SpuQuit() if you use SpuQuit() to turn functionality off. 


In the current specification, DMA transfer initialization is done after SouStart() is called. 


See also 
SpuQuit(), Spulnit(). 
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SpuStGetStatus 

Get SPU streaming status. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.2 12/14/98 

Syntax 


long SpuStGetStatus(voic) 
Explanation 
Determines the state of SPU streaming. 


Return value 
Table 15-12 SPU streaming status 








Attribute Description 

SPU_ST_NOT_AVAILABLE SPU streaming is not available; SpuStlnit() has not 
been called. 

SPU_ST_IDLE Data transfer to the sound buffer has not been 
performed yet or all streams have terminated. 

SPU_ST_PREPARE Transferring the first buffer. 

SPU_ST_TRANSFER Transferring the data to the sound buffer. 


If SouStTransfer (SPU_ST_PREPARE ) is executed for 
a voice in this state, status does not change to 
SPU_ST_PREPARE. 

SPU_ST_FINAL Waiting for the end of playback after transferring the 
last buffer. SouStTransfer() is not accepted in this 
state. 





See also 
SpuStlnit(), SouStTransfer(), SouStGetVoiceStatus() 
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SpuStGetVoiceStatus 

Determine voices used for SPU streaming. 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.2 12/14/98 

Syntax 


u_long SpuStGetVoiceStatus(voic) 


Explanation 
Determines the voices used for SPU streaming. 


Return Value 
Value of the voices represented by the bit OR of SPU_OCH ... SPU_23CH. 


See also 
SpuStTransfer(), SpuStGetStatus() 
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SpuStinit 


Initialize SPU streaming. 


Library Header File Introduced 
libspu.lib libspu.h 3.2 


Syntax 
SpuStEnv *SpuStlnit( 


long mode) Not used under the current specification. Pass "0". 


Explanation 
Initializes SPU streaming. Called only once in an executed program. 


Return Value 
Pointer to the SPU streaming environment structure SpuStEnv. 


See also 
SpuStQuit(), SpuStEnv() 
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Documentation Date 
12/14/98 
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SpuStQuit 


Complete SPU streaming. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.2 12/14/98 


Syntax 
long SpuStQuit(voia) 


Explanation 
Completes SPU streaming. Prior to calling this function, processing must be completed for all the streams. 


Return value 

SPU_ST_ACCEPT Normal end 

SPU_ST_WRONG_STATUS SpuStQuit() not accepted because current 
status is not SPU_ST_IDLE. 


See also 
SpuStlnit(), SouStGetStatus() 
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SpuStSetPreparationFinishedCallback 


Set function to be called at end of preparation phase of SPU streaming. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.2 12/14/98 
Syntax 


SpuStCallbackProc 
SpuStSetPreparationFinshedCallback( 
SpuStCallbackProc callback_proc) Pointer to calloack function 


SpuStCallbackProc callback_proc( 

u_long voice_bit, 

long status) 

Explanation 

Sets the callback function to be activated at the end of the preparation state of data transfer in SPU 
streaming. 

When callback_proc is called, it is passed the following arguments: 


e voice_bit specifies the voices for whom preparation transfer has completed. You can check the voices 
by using the bit values SPU_OCH to SPU_23CH. 
e status can be either SPU_ST_PREPARE (streaming is in preparation state) or SPU_ST_PLAY (playing) 


Return Value 
Pointer to the previously set callback function; NULL if no callback function was previously set. 


See also 
SpuStTransfer(), SouStSetTransferFinishedCallback(), SouStSetStreamFinishedCallback() 
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SpuStSetStreamFinishedCallback 


Set function to be called at completion of each stream in SPU streaming. 





Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.2 12/14/98 
Syntax 


SpuStCallbackProc 
SpuStSetStreamFinishedCallback( 
SpuStCallbackProc callback_proc) Pointer to callback function 


SpuStCallbackProc *callback_proc( 

u_long voice_bit, 

long status) 

Explanation 

Sets the callback function called at the completion of each stream in the SPU streaming. 





When callback_proc is called, it is passed the following arguments: 


e voice_bit specifies the voices for whom preparation transfer has completed. You can check the voices 
by using the bit values SPU_OCH to SPU_23CH. 
e status can be either SPU_ST_FINAL (streaming is in termination state) or SPU_ST_PLAY (playing) 


Return Value 
Pointer to the previously set callback function; NULL if no callback function was previously set. 


See also 
SpuStTransfer(), SouStSetPreparationFinishedCallback(), SouStSetTransferFinishedCallback() 
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SpuStSetTransferFinishedCallback 


Set function to be called at completion of one transfer to the stream buffer for all streams 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.2 12/14/98 
Syntax 


SpuStCallbackProc 
SpuStSetTransferFinishedCallback( 
SpuStCallbackProc callback_proc) Pointer to calloack function 


SpuStCallbackProc *callback_proc( 

u_long voice_bit, 

long status) 

Explanation 

Sets the callback function to be called at the completion of one transfer to the stream buffer for all the 
streams in the SPU streaming. 

When callback_proc is called, it is passed the following arguments: 


e voice_bit specifies the voices for whom transfer has completed. You can check the voices by using 
the bit values SPU_OCH to SPU_23CH. 
e status is always SPU_ST_PLAY (playing). 


Return Value 
Pointer to the previously set callback function; NULL if no callback function was previously set. 


See also 
SpuStTransfer(), SouStSetPreparationFinishedCallback(), SouStSetStreamFinishedCallback() 
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SpuStTransfer 

Prepare for a stream and provide instructions for starting it. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.2 12/14/98 

Syntax 

long SpuStTransfer( 

long flag, Stream state flag 

u_long voice_bit) Streaming voices 

Explanation 


Prepares for a stream in SPU streaming, and provides instructions for starting it. 





The voices for the stream are set in voice_bit by ORing the appropriate values SPU_OCH ... SPU_23CH. 
flag values are: 


e SPU_ST_PREPARE = Preparation 
Prepares the stream according to the attributes of the SpuStEnv structure returned by SpuStlnit(). 
After preparation, the callback function set by SouStSetPreparationFinishedCallback() is called. 

e SPU_ST_PLAY = Start 
The stream is started according to the attributes of the SpuStEnv structure returned by SpuSilnit(). 
If streaming status is SPU_ST_PREPARE, the voice is keyed on. If the status is SPU_ST_TRANSFER, 
the transfer waits until processing for the current streams is transferred to the latter part of the stream 
buffer. 
When one transfer to the stream buffer for all streams is completed, the callback function set by 
SpuStSetTransferFinishedCallback() is called, and the attributes for the next transfer for each stream 
are set. 
When a stream is completed, the callback function set by SouStSetStreamFinishedCallback() is called 
(just before the next transfer if other streams are processed.) 














Return value 





SPU_ST_ACCEPT Processing is accepted. 

SPU_ST_NOT_AVAILABLE SPU streaming is not available. SouStinit() 
has not been called. 

SPU_ST_INVALID_ARGUMENTS The value of the arguments is not in the 
specification. 

SPU_ST_WRONG_STATUS SpuStTransfer() not accepted. The causes 
are: 


e The current status is SPU_ST_FINAL. 
e flag is SPU_ST_PREPARE, and the current status is SPU_ST_PREPARE. 
e = flag is SPU_ST_PLAY, and the current status is SPU_ST_IDLE. 


See also 


SpuSilnit(), SouStSetPreparationFinishedCalloack(), SouStSetTransferFinishedCallback(), 
SpuStSetStreamFinishedCallback() 
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SpuWrite 

Transfer data from main memory to the sound buffer. 
Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuWrite( 

u_char “addr, Pointer to transfer data start address in main memory 

u_long size) Transfer data size (in bytes) 

Explanation 


Transfers size bytes of data from main memory addr to the sound buffer 


The main memory address adar storing the transfer data must be a global variable or an address in a heap 
area that was allocated by a function such as malloc(). It can’t address a variable on the stack declared in 
a function. 


SpuWrite() does not perform sound buffer memory management, so real waveform data cannot be used if 
the user does not transfer to addresses which avoid the following areas. 


e SPU decoded data transfer area: OxOO00-Oxfff 
e System reserved area: 0x1000-0x100f 
e Addresses after the reverb work area offset (start) address 


After calling, either call SoulsTransferCompleted() to confirm transfer completion or set the DMA transfer 
completion Callback function in advance using SpuSetTransferCalloack(). 


Due to the limitations of the DMA transfer hardware, transfers are always performed in 64 byte units. When 
specifying values which are not multiples of 64 as secondary arguments, since the portion of the value 
which is a multiple of 64 is transferred, it’s possible to damage the data in the SPU memory. 


Return value 
Transferred data size. If size is larger than 512 KB, the actual transferred size is returned. 


If the transfer mode is SPU_LTRANSFER_BY_DMA and size is not a multiple of 64, the return value will be 
incorrect. 


See also 

SpuWriteO(), SouWritePartly(), SouRead(), SouSetTransferMode(), SouGetTransferMode(, 
SpuSetTransferStartAddr(), SouGetTransferStartAddr(), SpulsTransferCompleted(), 
SpuSetTransferCallback() 
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15-138 Basic Sound Library Functions 


SpuWriteO 


Clear sound buffer. 


Library Header File Introduced Documentation Date 
libspu.lib libspu.h 3.0 12/14/98 


Syntax 

u_long SpuWrite0( 

u_long size) Clear area size (in bytes) 

Explanation 

Writes Os in the sound buffer area starting at the address specified by SpuSetTransferStartAddr(). The 
number of bytes written is size. The writing is done by DMA transfer, but is started synchronously. 


Due to the limitations of the DMA transfer hardware, transfers are always performed in 64 byte units. When 
specifying values which are not multiples of 64 as secondary arguments, since the portion of the value 
which is a multiple of 64 is transferred, it’s possible to damage the data in the SPU memory. 


Return value 
The size of the area cleared. If size is larger than 512 KB, the actual written size is returned. 





See also 


SpuWriteQ, SpuWritePartly(), SouRead(), SouSetTransferMode(), SouGetTransferMode(), 
SpuSetTransferStartAddr(), SouGetTransferStartAddr() 
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SpuWritePartly 

Transfer data from main memory to sound buffer (assuming the transfer is divided into sections). 
Library Header File Introduced Documentation Date 
libspu. lib libspu.h 3.0 12/14/98 

Syntax 

u_long SpuWritePartly( 

u_char “addr, Pointer to transfer data start address in main memory 

u_long size) Transfer data size (in bytes) 

Explanation 


Transfers data from main memory to the sound buffer. 


The main memory address holding the transfer data must be a global variable or a variable in a heap area 
allocated by a function such as malloc(). It can’t be a stack variable declared in a function. 


Data is transferred from the address specified in SouSetTransferStartAddr(), and after completion of the 
transfer specified by size, the starting address is incremented by size, and stored internally. 





In the case of continuous transfer, the size of each transfer must be divisible by 8, except for the final block. 





If SouSetTransferStartAdadr() is called during continuous transfer processing, correct continuous transfer is 
not guaranteed. 





SpuWritePartly() does not perform sound buffer memory management, so real waveform data cannot be 
used if the user does not transfer to addresses which avoid the following areas. 


e SPU decoded data transfer area: OxOO00-Oxfff 
e System reserved area: 0x1000-0x100f 
e Addresses after the reverb work area offset (start) address 





After calling, either call SoulsTransferCompleted() to confirm transfer completion or set the DMA transfer 
completion Callback function in advance using SpuSetTransferCallback. 


Due to the limitations of the DMA transfer hardware, transfers are always performed in 64 byte units. When 
specifying values which are not multiples of 64 as secondary arguments, since the portion of the value 
which is a multiple of 64 is transferred, it’s possible to damage the data in the SPU memory. 


Return value 
Transferred data size. If size is larger than 512 KB, the actual transferred size is returned. 


If the transfer mode is SPU_LTRANSFER_BY_DMA and size is not a multiple of 64, the return value will be 
incorrect. 





See also 

SpuWriteQ, SpuWriteO(), SouRead(), SouSetTransferMode(), SouGetTransferMode(), 
SpuSetTransferStartAddr(), SouGetTransferStartAddr(), SpulsTransferCompleted(), 
SpuSetTransferCallback() 
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AddSIO 


Initialize SIO driver. 


Library Header File Introduced Documentation Date 
libsio.lib libsio.h 3.6 12/14/98 


Syntax 
long AddSIO( 
int baud) Communication speed (bps) 


Explanation 
Initializes the SIO driver at the communication speed baud. 


Return value 
1. 


See also 
DelSIO() 
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DelSIO 


Delete SIO driver from kernel. 


Library Header File Introduced Documentation Date 
libsio.lib libsio.h 3.6 12/14/98 


Syntax 
long DelSIO(voic) 


Explanation 
Deletes the SIO driver from the kernel. 


Return value 
1. 


See also 
AddSlo() 
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Sio1 Callback 

Set SIO interrupt callback function. 
Library Header File Introduced Documentation Date 
libsio.lib libsio.h 4.0 12/14/98 

Syntax 

int Sio1 Callback( 

void(*func)() Callback function 

Explanation 


Defines func as the callback to be triggered when an interrupt has been generated by the interrupt factors 
(CR_DSRIEN, CR_RXIEN, CR_TXIEN) set by _sio_control (1,1, param). If func is O, a callback is not 
generated. 


When an interrupt is generated, the interrupt flag must be cleared using _sio_control (2,1,0) or _sio_control 
(1,1,CR_ERRRST). The next SIO interrupt isn’t generated unless the interrupt flag is cleared. 








Return value 
Address of previously installed callback function. 
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_sio_control 


Issue SIO command 


Library Header File Introduced Documentation Date 
libsio. lib libsio.h 3.6 12/14/98 

Syntax 

long _sio_control( 

unsigned long cmd Command 

unsigned long arg Subcommand 

unsigned long param) Argument 


Explanation 
SIO driver control and information acquisition. 


Used in detailed communication with the PC and also when the user wishes to suppress debugging data 
based on the standard output from the library, etc. 


Table 16-1: Command Summary 





























cmd arg Function 
0 0 Returns driver status (see Table 16-2) 
1 Returns control line status (see Table 16-3) 
2 Returns communications mode (see Table 
16-1) 
3 Returns communications speed (bps units) 
4 Reads 1 byte 
1 O System reservation 
1 Sets param value as control line status (see 
Table 16-3) 
2 Sets param value as communications mode 
(see Table 16-4) 
3 Sets param value as communications speed 
(bps units) 
4 Writes 1 byte 
2 (0) Resets driver 
1 Clears driver status error-related bits 
Table 16-2: Driver Status 
bit Contents 
31-10 Undecided 
9 SR_IRQ 1: interrupt on 
8 SR_CTS 1: CTS is on 
7 SR_DSR 1: DSR is on 
6 Undecided 
5 SR_FE 1: frame error occurs 
4 SR_OE : overrun error occurs 
3 SR_PERROR : parity error occurs 
2 SR_TXU : no communications data 
1 SR_RXRDY : able to read communications data 
O SR_TXRDY : able to write communications data 
Table 16-3: Control Line Status 
bit Contents 
31-2 undecided 
1 1: RTS is on 
0 1: DTR is on 
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Table 16-4: Communications Mode 








bit Contents 

31-8 Undecided 

7,6 stop bit length 
MR_SB_01 01:1 
MR_SB_10 10: 1.5 
MR_SB_11 11:2 

5 MR_P_EVEN parity 2 (1: odd 0: even) 

4 MR_PEN parity 1 (1: exists) 

3,2 character length 
MR_CHLEN_5 00: 5 bit 
MR_CHLEN_& 01:6 
MR_CHLEN_7 10: 7 
MR_CHLEN_8 11:8 

1 Always 1 

O Always O 





Return value 
Described in Table 16-1 above. 
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Table 16-5: Control Register 











bit Contents 

31-13 Undecided 

12 CR_DSRIEN 1: DSR Interrupt Permission 

11 CR_RXIEN 1: Receive Interrupt Permission 
10 CR_TXIEN 1: Transmission Interrupt Permission 
9,8 O Fixed 

7 Undecided 

6 CR_INTRST 1: SIO1 Reset 

5 CR_RTS 1: RTS is on 

4 CR_ERRRST 1:Interrupt and error flag clear 
3 Undecided 

2 CR_RXEN 1: Receive permission 

1 CR_DTR 1: DTR is on 

O CR_TXEN 1: Transmission permission 
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Structures 
GsARGUNIT 
Primitive driver argument area. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
} GSARGUNIT; 
Explanation 


The common arguments passed to a primitive driver called from GsSortUnit(). 


For high speed operation, use the scratch pad. 


See also 
GsSortUnit(), GSU_...(, GsU_040100...() 
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GsARGUNIT_ANIM 


Animation driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT “*tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET *out_packetp; Pointer to unused packet area 
long header_size; Size of primitive header used in animation 
u_long *htop; Start address of interpolation function table section 
u_long *ctop; Start address of sequence control section 
u_long “ptop; Start address of parameter section 


} GSARGUNIT_ANIM; 


Explanation 

The arguments passed to an animation primitive driver called from GsSortUnit(). In addition to the common 
arguments in GSARGUNIT, it also contains the start address for each section needed for the primitive 
header size and animation. 





The argument transfer area is larger than this structure. A pointer to the section where rewriting is carried 
out follows GSARGUNIT_ANIM. This pointer plus htop, ctop, and ptop are included in header_size. 





The transfer area for the interpolation function follows the pointer to the rewriting section. 





GsARGUNIT_ANIM 
header_size 





Ptr to rewrite section 





Interpolation driver 
Argument transfer area 











The size and meaning of the interpolation driver transfer area depends on the type of interpolation function. 
the following four parameters apply to linear interpolation: 


1. Sequence pointer start address 

2. Interpolation source parameter address. 

3. Interpolation destination parameter address. 

4. Address which remembers parameters after interpolation. 


For high speed operation, use the scratch pad. 


See also 
GsSortUnit(), GsU_O38000001...(), GsU_O3S000000(),GsU_03010110...() 
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GsARGUNIT_GND... 


HMD ground primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.1 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when sorting OT 
int offset; OT screen coordinate system Z-axis offset 


PACKET “out_packetp; 
u_long “polytop; 
u_long “boxtop; 
u_long “pointtop; 
SVECTOR “*nortop; 


} GSARGUNIT_GND; 


typedef struct { 


u_long “primp; 

GsOT *tagp; 

int shift; 

int offset; 

PACKET “out_packetp; 
u_long “polytop; 
u_long “boxtop; 
u_long “pointtop; 
SVECTOR “*nortop; 
u_long “uvtop; 


Pointer to unused packet area 

Pointer to start of ground POLYGON section 
Pointer to start of ground box section 
Pointer to start of ground vertex section 
Pointer to start of NORMAL section 


Primitive start address 

Pointer to current GSOT 

Number of bits to shift when sorting OT 

OT screen coordinate system Z-axis offset 
Pointer to unused packet area 

Pointer to start of ground POLYGON section 
Pointer to start of ground box section 
Pointer to start of ground vertex section 
Pointer to start of NORMAL section 

Pointer to start of UV section 


} GSARGUNIT_GNDT; 


Explanation 
The arguments passed to a ground primitive driver called from GsSortUnit(). GSARGUNIT_GNDT uses 
texture, while GSARGUNIT_GND does not. 


This structure includes pointers to the start of the ground POLYGON section, the box section, and the 
vertex section within HMD data, in addition to the parameters in GSARGUNIT. 





Use the scratch pad to improve performance. 


See also 
GsSortUnit(), GsU_...() 
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17-6 HMD Library Structures 


GsARGUNIT_IMAGE 


Image primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT “*tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
u_long *imagetop; Pointer to pixel data start 
u_long *cluttop; Pointer to clut data start 


} GSARGUNIT_IMAGE; 


Explanation 


The arguments passed to an image primitive drive called from GsSortUnit(). In addition to the GSARGUNIT 
members, it includes the pointer to the start of the clut data and texture image pixel data. 





For high speed operation, use the scratch pad. 


See also 
GsSortUnit(),GsU_...() 
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GsARGUNIT_JntMIMe 


Joint MIMe primitive driver argument area. 














Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
u_long *coord_sect; Pointer to COORDINATE section top 
long *mimepr; Pointer to mime coefficient area 
u_long mimenum; Number of mime keys 
u_short mimeid; MiMelD 
u_short reserved; 
u_long *mime_diff_sect; Pointer to MIMe DIFF section 


} GSARGUNIT_JntMIMe; 


Explanation 


The arguments passed to a joint MIMe primitive driver called from GsSortUnit(). In addition to the 
GsARGUNIT parameters, it contains a pointer to the coordinate section start within the HMD data, the 
pointer to the mime coefficient area, the number of mime keys, the MIMelD, and the MIMe DIFF section 
pointer. 








For high-speed operation, use the scratch pad. 


See also 
GsSortUnit(), GSU_...(), GSU_0401 00. ..() 
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GsARGUNIT_NORMAL 


Independent primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
u_long “primtop; Pointer to POLYGON section top 
SVECTOR *vertop; Pointer to VERTEX section top 
SVECTOR *nortop; Pointer to NORMAL section top 


} GSARGUNIT_NORMAL; 


Explanation 


The arguments passed to an independent primitive driver called from GsSortUnit(). In addition to the 
GsARGUNIT parameters, it contains the POLYGON section and VERTEX sections within the HMD data, 
and the pointer to the NORMAL section start. 


For high-speed operation, use the scratch pad. 


See also 
GsSortUnit() 
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GsARGUNIT_RstJntMIMe 


Joint mime reset primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT “*tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
u_long *coord_sect; Pointer to COORDINATE section top 
u_short mimeid; MIMelD 


u_short reserved; 
u_long *mime_diff_sect; Pointer to MIMe DIFF section 


} 
GsARGUNIT_RstJntMIMe; 


Explanation 


The arguments passed to a joint MIMe reset primitive driver called from GsSortUnit(). In addition to the 
GsARGUNIT parameters, it contains the pointer to the start of the COORDINATE section within the HMD 
data, the MIMelD and the MIMe DIFF section pointer. 


For high-speed operation, use the scratch pad. 


See also 
GsSortUnit(), GSU_040100...() 
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GsARGUNIT_RstVNMIMe 


Argument area of vertex normal MIMe reset primitive driver. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
u_short mimeid; MIMelD 
u_short reserved; 
u_long *mime_diff_sect; MIMe DIFF section pointer 
SVECTOR “orgs_vn_sect; OrgsVN section pointer 
SVECTOR ‘*vert_sect; Vertex section pointer 
SVECTOR *norm_sect; Normal section pointer 


} GSARGUNIT_RstVNMIMe; 


Explanation 


The arguments passed to a vertex normal primitive driver called from GsSortUnit. In addition to the 
GsARGUNIT parameters, it contains the MIMelD within the HMD data, the MIMe DIFF section pointer, the 
OrgsVN section pointer, the vertex section pointer, and the normal section pointer. 


For high-speed operation, use the scratch pad. 


See also 
GsSortUnit(),GsU_...(, GsU_040100...() 
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GsARGUNIT_SHARED 


Shared primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primitive start address 
GsOT “*tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
u_long “primtop; Pointer to unused packet area 
SVECTOR *vertop; Pointer to POLYGON section top 
GsWORKUNIT *vertop2; Pointer to shared VERTEX section top 
SVECTOR *nortop; Pointer to area storing the calculation results of shared vertex section 
SVECTOR *nortop2; Pointer to shared NORMAL section top 
} GSARGUNIT_SHARED; Pointer to area storing the calculation results of the shared NORMAL 
section 
Explanation 


The arguments passed to a shared primitive driver called from GsSortUnit(). In addition to the GSARGUNIT 
parameters, it contains the POLYGON section and VERTEX section within the HMD data, the pointer to the 
NORMAL section start, and the pointer to the area storing those calculation results. 


For high-speed operation, use the scratch pad. 


See also 
GsSortUnit(), GsU_...() 


Run-Time Library Reference 


17-12 HMD Library Structures 


GsARGUNIT_VNMIMe 


Vertex normal mime primitive driver argument area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
u_long “primp; Primtive start address 
GsOT *tagp; Pointer to current GSOT 
int shift; Number of bits to shift when assigning OT 
int offset; OT screen coordinate system Z-axis offset 
PACKET “out_packetp; Pointer to unused packet area 
long *mimepr; Pointer to mime coefficient area 
u_long mimenum; Number of mime keys 
u_short mimeid; MIMelD 
u_short reserved; 
u_long *mime_diff_sect; MIMe DIFF section pointer 
SVECTOR “orgs_vn_sect; OrgsVN section pointer 
SVECTOR *vert_sect; Vertex section pointer 
SVECTOR *norm_sect; Normal section pointer 


} GSARGUNIT_VNMIMe; 


Explanation 


The arguments passed to the vertex normal mime primitive driver called from GsSortUnit(). In addition to 
the GSARGUNIT parameters, it contains the MIMelD within the HMD data, the MIMe DIFF section pointer, 
the OrgsVN section pointer, the vertex section pointer, and the normal section pointer. 


For high-speed operation, use the scratch pad. 


See also 
GsSortUnit(),GsU_040100...() 
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GsCOORDUNIT 
Matrix type coordinate system. 
Library Header File Introduced Documentation Date 
libhmd.lib libhma.h 4.0 9/1/99 
Structure 
struct GsCOORDUNIT { 
u_long fig; Flag indicating whether matrix was rewritten 
MATRIX matrix; Matrix 
MATRIX workm; Result of multiplication from this coordinate system to the 
WORLD coordinate system 
SVECTOR rot; Rotation vector for creating matrix 


struct GSCOORDUNIT *super; Pointer to parent coordinates 
} GSCOORDUNIT; 


Explanation 

GsCOORDUNIT has parent coordinates and is defined by matrix. workm retains the result of multiplication 
of matrices performed by GsGetLwUnit() and GsGetLsUnit() in each node of GSCOORDINATE2 using the 
WORLD coordinates. However, this result is not stored in the workm of the coordinate system directly 
connected to the WORLD coordinate system. 


GsGetLwuUnit() and GsGetLsUnit() use fig to omit calculations for a node when they have already been 
performed. The external variable PSDCNT sets the flag and 0 clears it. If you change the contents of 
matrix, you must clear this flag. If it is not cleared, GsGetLwUnit() and GsGetLsUnit() will fail to execute 
normally. 


See also 
GsGetLwuUnit(), GsGetLsUnit(), GsGetLwsUnit(), GsMapCoordUnit() 
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GsRVIEWUNIT 
HMD viewpoint position (Reference type). 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
long vpx, vpy, vpz; Viewpoint coordinates 
long vrx, Vry, VIZ; Reference point coordinates 
long rz; Viewpoint twist 
GsCOORDUNIT “super; Pointer to coordinate system which sets viewpoint (G8COORDUNIT 
type) 
} GSRVIEWUNIT; 
Explanation 


GsRVIEWUNIT contains viewpoint information and is set by GsSetRefViewUnit(). The viewpoint coordinates 
in the coordinate system displayed by super are set in vpx, voy and vpz. The reference point coordinates in 
the coordinate system displayed by super are set in vrx, vry and vrz. 


When the z axis is a vector from the viewpoint to the reference point, rz specifies the screen inclination 
against the z axis in fixed decimal format, with 4096 set to one degree. Viewpoint and reference point 
coordinate systems are set in super. For an example of the use of this function, an airplane cockpit view 
can be realized simply by setting super to the airplane coordinate system. 





See also 
GsSetRefViewUnit(), GsSetRefViewLUnit() 
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GsSEH 
HMD animation sequence header. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
short idx; Indexes the sequence control descriptor of the sequence header and 
represents it in the index within the sequence control section 
u_char sid; Sequence ID 
u_char pad; System reservation 
} GsSEH; 
Explanation 


Contains sequence information. Multiple sequences are stored as an array of GSSEH after the sequence 
pointer. 


idx provides the index to the sequence control descriptor of the sequence playback start. This index is set 
to GsSEQ.ti. By setting GSSEH.sid to GSSEQ.sid, playback of the sequence can be started. 








When multiple sequences are present, select one from the GSSEH array and update the value to GSSEQ. 





pad may be freely used if TOD animation is not used. 


See also 
GsLinkAnim(), GSU_O3000000(), GsU_03000001...() 
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GsSEQ 
HMD animation sequence pointer. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 03/06/00 
Structure 
typedef struct { 
u_long rewrite_idx; The upper 8 bits are a word offset into the animation primitive header, which 


contains a pointer the section to be updated. The lower 24 bits are the 
relative offset (in word units) within that section. 





u_short size; Size up to area where next sequence pointer is stored. 

u_short num; Number of sequences stored in this sequence pointer. 

u_short ii; Index of area which stores parameters after interpolation (Relative offset 
within parameter section) 

u_short aframe; Frame count of sequence. Automatically decreased by the frame update 


driver. The sequence stops at 0. For endless playback, set it to Oxffff, and 
the decrease is prohibited. 

u_char sid; Current status sequence ID of the currently playing sequencer. 
Matching can be achieved when performing sequence jump and END 
operations with the sequence ID value set from O to 127. The sequence flow 
can be controlled using SID. When performing a jump description with the 
sequence control descriptor, it defines the match SID and the SID of the 
location to be jumped to. By setting the match SID to O, it is possible to 
match all SIDs. 

char speed; Controls sequence playback speed. The two’s complement of the sign bit 
indicates the direction of playback. Standard playback speed is 0x10. Ox7f 
increases speed eight times, and OxO1makes speed 1/16. The sign bit is the 
bit used for reverse playback. The packaging is carried out by subtracting 
speed from rframe frame by frame to make a new RFRAME value. 

















u_short srcii; Retains data which should be specified in ii. The area for parameter saving 
already included in the data is retained by the index. 

short rframe; In the interpolation coefficient O between the key frames SRC FRAME, 
rframe==tframe becomes DST FRAME. It is a 12 bit fixed-point number. 

u_short tframe; The distance between key frames, as a 12-bit fixed-point number. The 





tframe in the sequence control descriptor is 8 bits and shifts four bits to the 
left when updated to GSSEQ.tframe. When tframe is O, the unobtained 
frame update driver passes the next key frame in DST KEYFRAME (the 
interpolated target key frame). 











u_short ci; Index to the parameter which retains source key frames (Word offset within 
parameter section) 

u_short ti; Parameter index which retains destination keyframes (Word offset within 
parameter section) 

u_short start; The sequence start index. start is copied to ti and rframe set to zero when 


sequence begins. The work area indicated for Bspline and related 
interpolation is set in this member. 


u_char start_sid; Stream ID of sequence to be started. start_sid is copied to sid when 
sequence begins. 
u_char traveling; Clears to O when the key frame is switched. Programmers can use this 
member for a variety of purposes. 
} GSSEQ; 
Explanation 


GsSEQ contains the frame update driver internal status. By rewriting this structure during execution, 
animation can be dynamically controlled. 





GsSEQ structures in the HMD data can be indicated using GsLinkAnim(). The following members are only 
referred to by the frame update driver: rewrite_idx, size, num, ii, speed, srcii, start and start_sid. All others 
are rewritten by the frame update driver. 








Run-Time Library Reference 


HMD Library Structures 17-17 


See also 
GsU_03000000(), GsU_03000001...(), GsLinkAnim() 
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GsTYPEUNIT 


Type storage area. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 


Structure 
typedef struct { 

u_long type; Primitive type 

u_long “ptr; Address in HMD data where type is stored 
} GSTYPEUNIT; 


Explanation 


This structure is passed to GsScanUnit(). By assigning the subordinate functions corresponding to the type 
to ptr, the type is overwritten on the subordinate functions pointer. GsSortUnit() calls that subordinate 
function. 





The structure of type is as follows: 


32 28 24 20 16 12 





DEV CATE 


| JC 
NIL 
ID GORY | |p 


VAM 
40W 
<U> 
HOr 
QOT 
ţi 











DRIVER PRIMITIVE TYPE 


Table 17-1 





DEV ID: 
0000: SCE Reserved 


CATEGORY: 
0000: Polygon 
0001: Shared Polygon 
0010: Image data 
0011: Animation 
0100: MIMe 
0101: Ground 
0111: Equiopment 
DRIVER: 
INI(init) 0: None 
1: COORDINATE 
initialization is needed 
CLP(clip) 0: No clipping 
1: No clipping on left and 
top of screen 
STP(Semi-trans) 0: Semi-transparent 
1: Semi-transparent 
BOT(both-side) 0: One-sided polygon 
1: Two-sided polygon 
ADV(active-div) 0: No automatic division 
1: With automatic division 
LGTi(light) O: With light source 
calculation 
1: Without light source 
calculation 
FOG(fog) 0: FOG off 
1: FOG on 
DIV(divide) O: Without division 
1: With division 
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PRIMITIVE TYPE: 
TILE 


PST(preset) 
MIP(mip-map) 
LMDilight-mode) 
CODE 


IIP 


COL(colored) 


TME 


HMD Library Structures 


0: No information for 
continous texture 

1: With information for 
continous texture 

0: No presets 

1: With presets 

0: No mip-map 

1: With mip-map 

0: With normals 

1: No normals 

000: Reserved 

001: Triangle 

010: Quadrangle 

011: strip mesh 
100-111: Reserved 

O: Flat 

1: Gouraud 

O: 1 quality color within 
identical polygon 

1: Color for every vertex 
O: Texture mapping OFF 
1: Texture mapping ON 











See also 
GsMapCoordUnit(), GsScanUnit(), GsSortUnit() 
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GsUNIT 


Three-dimensional object handler for GsSortUnit(). 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 


Structure 
typedef struct { 
GsCOORDUNIT *coord; Pointer to local coordinate system 
u_long *primtop; Pointer to primitive block header 
} GsUNIT; 


Explanation 


GsUNIT exists in every HMD data primitive block and allows movement of three-dimensional models. 
GsSortUnit() is used to register GSUNIT to the ordering table. coord is the pointer to the primitive block 
individual coordinate system. By setting the matrix in the coordinate system pointed to by coord, the 
object's location, inclination and size are reflected. 








The primitive block start address is passed in primtop. 


See also 
GsSortUnit(), GsU_OO...() 
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GsVIEWUNIT 
HMD viewpoint position (matrix type). 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Structure 
struct GSVIEWUNIT { 
MATRIX view; Matrix used to change from parent coordinates to viewpoint coordinates 
GsCOORDUNIT “super; Pointer to coordinate system which sets viewpoint 
} 
Explanation 


This structure sets the viewpoint coordinates used by HMD. It directly specifies the matrix used to change 
from parent coordinates to viewpoint coordinates. The function used to set GsVIEWUNIT is 
GsSetViewUnit(). 


See also 
GsSetViewUnit() 
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GsWORKUNIT 
Calculation result storage area for shared primitive. 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 12/14/98 
Structure 
typedef struct { 
DVECTOR vec; Area which stores the thre-dimensional coordinate values and the two- 
dimensional coordinate values after perspective conversion. 
short otz; Area which stores the OTZ value obtained when vec is requested 
short p; Area which stores the interpolation value obtained when vec is requested 
} GSWORKUNIT; 
Explanation 


When using a shared primitive, first a perspective conversion of each three-dimensional coordinate value is 
carried out by its matrix to convert it into a two-dimensional coordinate. After perspective conversion is 
completed by the matrices, the shared primitive refers to the converted two-dimensional coordinate and 
creates a packet. This structure is the area which stores the results of that calculation. 





See also 
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Functions 
GsGetHeadpUnit 
Obtain current HMD header address. 
Library Header File Introduced Documentation Date 
libhma.lib libhmd.h 4.0 12/14/98 
Syntax 


u_long *GsGetHeadpUnit(voia) 


Explanation 
Returns the current type header address when using GsScanUnit() to scan HMD data. 


Return value 
The current type header address. 


See also 
GsScanuUnit() 
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GsGetLsUnit 

Calculate a local screen matrix. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 9/1/99 

Syntax 


void GsGetLsUnit( 
GsCOORDUNIT *coord, Local coordinates 
MATRIX *m) Matrix 


Explanation 


Calculates a local screen perspective transformation matrix from the GSCOORDUNIT structure pointed to 
by coord and stores the result in the MATRIX structure pointed to by m. 


For high speed operation, the function retains the result of calculation at each node of the hierarchical 
coordinate system. When GsGetLsUnit() is called next, calculations up to the node to which no changes 
have been made are omitted. This is controlled by a GSCOORDUNIT member flag (libgs replaces the 
external variable PSDCNT in flags already calculated by GSCOORDUNIT). 


If the contents of a superior node are changed, the effect on a subordinate node is handled by libgs, so it is 
not necessary to clear the flags of all subordinate nodes of the changed superior node. 
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GsGetLwsUnit 

Calculate local world and local screen matrices. 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 12/14/98 

Syntax 


void GsGetLwsUnit( 
GsCOORDUNIT *coord, Pointer to local coordinates 


MATRIX *w, Matrix which stores local world coordinates as the result 
MATRIX */s) Matrix which stores local screen coordinates as the result 
Explanation 


Calculates both local world coordinates and local screen coordinates. It is faster than calling GsGetLwUnit() 
and then calling GsGetLsUnit(). This is a quick way of obtaining a local world matrix (Iw) to pass to 
GsSetLightMatrix() to carry out light source calculations. 


See also 
GsGetLwUnit(), GsGetLsUnit() 
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GsGetLwUnit 

Calculate local world matrix. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 9/1/99 

Syntax 


void GsGetLwUnit( 
GsCOORDUNIT *coord, Local coordinates 
MATRIX *m) Matrix 


Explanation 


Calculates a local screen perspective transformation matrix from the GSCOORDUNIT structure pointed to 
by coord and stores the result in the MATRIX structure pointed to by m. 


For high speed operation, the function retains the result of calculation at each node of the hierarchical 
coordinate system. When GsGetLwuUnit() is called next, calculations up to the node to which no changes 
have been made are omitted. This is controlled by a GSCOORDUNIT member flag (libgs replaces the 
external variable PSDCNT in flags already calculated by GSCOORDUNIT). 


If the contents of a superior node are changed, the effect on a subordinate node is handled by libgs, so it is 
not necessary to clear the flags of all subordinate nodes of the changed superior node. 








See also 
GsGetLsUnit(), GsGetLwsUnit() 
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GsInitRstNrmMIMe 

Initialize HMD normal MIMe driver. 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.1 12/14/98 

Syntax 

void GsInitRstNrmMIMe( 

u_long “primtop, Primitive start address 

u_long “hp) Primitive header start address 

Explanation 


Initializes the HMD library normal MIMe driver. 


When using the normal MIMe reset driver (GSU_04010029), it is necessary to initialize data using this 
function. When the address of the primitive driver is placed in the ptr of the GsTYPE structure which is 
returned by GsScanUnit(), GsInitRstNrmMIMe( is called. 





Refer to: psx\sample\graphics\hmd\mime\. 


See also 
GslnitRstVtxMIMe(), GSU_04010010....() 
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GslInitRstVtxMIMe 

Initialize HMD vertex MIMe driver. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.1 12/14/98 

Syntax 

void GsInitRstVtxMIMe( 

u_long “primtop, Primitive start address 

u_long “hp) Primitive header start address 

Explanation 


Initializes the HMD library vertex MIMe driver. 


When using the vertex MIMe reset driver (GSU_04010028), it is necessary to initialize data using this 
function. When the address of the primitive driver is placed in the ptr of the GSTYPEUNIT structure which is 
returned by GsScanUnit(), GsInitRstVtxMIMe( is called.. 





Refer to: psx\sample\graphics\hmd\mime\. 


See also 
GslnitRstNrmMIMe(), GSU_04010010....() 
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GsLinkAnim 

Link GSSEQ array and HMD data. 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 8/9/99 

Syntax 

int GsLinkAnim( 

GsSEQ *seg, GsSEQ structure array address 

u_long “p) Address of first type animation section 

Explanation 


Links a GSSEQ structure, which contains information to control one sequence, to corresponding data in an 
HMD file. As with GsScanAnim(), GsLinkAnim() must be activated during global SCAN. 


By using seq, the programmer can control animation playback in real time. With GsLinkAnim(), specific 
members of specific sequences such as seq[3]->aframe = 100 can be operated after switching to 
GsLinkAnim(. 


Information on each individual sequence can be accessed in the sequence header GSSEH. For example, 
assuming that ten sequences are defined in the fifth sequence, in order to play back the fourth, the fourth 
start index can be transmitted in the sequence pointer as follows: 


seq[5]->ti = (GSSEQ *)(&seq[5].start)+3)->sid; 








Return value 
Returns the linked number. 


See also 
GsScanAnim() 
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GsMapCoordUnit 

Map COORDINATE within the HMD data to actual address. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 

Syntax 

GsCOORDUNIT *GsMapCoordUnit( 

u_long *base, HMD data start address 

u_long *p) Type of address where INI (init) bits are set up 

Explanation 


In cases where COORDINATE exists within the HMD data, one type in which INI bits are set up exists in 
GsTYPEUNIT type when GsScanUnit() is carried out. In such cases, by transferring that type address to 
GsMapCoordUnit(), the COORDINATE TOP within the data and super within COORDINATE are converted 
to the actual address. 


Return value 
COORDINATE section start address. 


See also 
GsMapuUnit(), GsScanUnit() 
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GsMapUnit 

Map HMD data offset to actual address. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 

Syntax 

void GsMapUnit( 

u_long “p) HMD data start address 

Explanation 





In HMD data, sections are referred to by pointers. When creating HMD data, the pointers are specified as 
word offsets from the start of HMD data, because the exact memory locations are not known. GsMapUnit() 
converts these into actual addresses, so the HMD data can be used. 











A flag in the HMD header records whether addresses have been mapped, so there are no adverse effects 
even if GsMapUnit() is called again. 


See also 
GsScanUnit(), GsSortUnit() 
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GsScanAnim 
Perform SCAN for HMD animation. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Syntax 
u_long *GsScanAnim( 
u_long *p, Address where animation section first type exists. 
When p is O, the type following that previously called by GsScanAnim() is 
examined 
GsTYPEUNIT *ut) Pointer to area in which the type and its address are stored 
Explanation 


HMD data scanning is divided into two parts: 


e GsScanUnit() carries out a common scan of all sections (a global scan). 
e A dedicated scan function carries out a local scan of each section. GsScanAnim() is a dedicated scan 
function for HMD animation. 


Scanning should be carried out after the animation type has been globally scanned. Since a bit is attached 
to the INI field of the animation type which was first globally scanned at the authoring level, timing for 
performing a local scan can be gauged by closely watching that bit. 


GsScanAnim() is called to scan the types of all animation sections using the following procedure: 


1. If the Type selected in the global SCAN is category 3 (animation) and the INI bit is 1, a local SCAN 
should be performed (Type=O0x03800000). 

2. GsScanAnim() issues the above-mentioned type address as p. 

3. If the return value is O, data is wrong. If it is 1, issue GsScanAnim() once more. 

4. An interpolation primitive driver function pointer corresponding to the selected ut.type is replaced by 
ut. tr. 

5. Return to #3 and repeat until O is returned. 








With the primitive driver pointer which was written over by the HMD data, there are no adverse effects even 
if GsScanAnim( is called again. 





Return value 


O type to be scanned does not exist 
1 Scan successful, type exists 





See also 
GsScanUnit(), GsLinkAnim() 
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GsScanUnit 

Examine types within HMD data. 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 12/14/98 

Syntax 

int GsScanUnit( 

u_long *p, Block start address. When it is O, the type following that previously called by 

GsScanuUnit() is examined 

GsTYPEUNIT “ut, Pointer to area where the type and its address are stored 

GsOT “ot, Pointer to the OT 

u_long “scratch) Specifies scratch pad address 

Explanation 


HMD data is divided by type and primitive drivers are called according to type. By overwriting the type by 
address of the primitive driver, the primitive driver can be called during GsSortUnit(). On examination of the 
contents of GSTYPEUNIT returned by GsScanUnit() the pointer to the primitive driver is replaced by one 
which can be freely used by the user. 











GsScanUnit() internally copies the type corresponding to the header to scratch. By passing scratch as a 
primitive driver argument, the primitive driver can be activated. Generally, image primitives which are only 
activated once (such as GSUIMGO and GsUIMG1) are activated at this initialization. 





Initially, set o to the block start address when calling GsScanUnit(); subsequent calls should set p to 0, and 
it will scan to the end of the block. This operation is carried out for every block. 


Since a flag is attached to the primitive driver pointer which was written over by the HMD data, there are no 
adverse effects even if GsScanUnit() is called again. 


Return value 


O Reached the end of the block, type does not exist 
1 Type exists 
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GsSetRefViewLUnit 

Set HMD viewpoint position (High precision). 
Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 12/14/98 

Syntax 

int GsSetRefViewLUnit( 

GsRVIEWUNIT *ov) Viewpoint position information (viewpoint observation point type) 

Explanation 


Calculates GSWSMATRIX from viewpoint information. Its parameter is the GSRVIEWUNIT structure. If the 
viewpoint is not moved, GSWSMATRIX doesn’t change, so in such cases there is no need to call each 
frame. 








However, if the viewpoint is moved, the changes aren’t reflected unless each frame is called. Although the 
number of calculation mistakes using this function is smaller than with GsSetRefViewUnit(), the execution 
time is double. When the GSRVIEWUNIT super member is set to anything besides WORLD, even if the 
other parameters remain unchanged, the viewpoint moves if the parent coordinate system parameters are 
changed.In such cases, GsSetRefViewLUnit() must be called for each frame. 


Return value 
If viewpoint setting is successful:0; if unsuccessful:1. 
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GsSetRefViewUnit 
Set HMD viewpoint position. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 


Syntax 

int GsSetRefViewUnit( 

GsRVIEWUNIT *ov) Viewpoint position information (viewpoint observation point type) 
Explanation 


Calculates GSWSMATRIX from viewpoint information. If the viewpoint isn’t moved, GSWSMATRIX doesn’t 
change, so in such cases there is no need to call each frame. 





However, if the viewpoint is moved, the changes aren’t reflected unless each frame is called. When the 
GsRVIEWUNIT super member is set to anything besides WORLD, even if the other parameters remain 
unchanged, the viewpoint moves if the parent coordinate system parameters are changed. In such cases, 
GsSetRefViewUnit() must be called for each frame.. 





Return value 
If viewpoint setting is successful:0; if unsuccessful:1. 
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GsSetViewUnit 
Set HMD viewpoint. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 


Syntax 


int GsSetViewUnit( 
GsVIEWUNIT *pv) Viewpoint position information (matrix type) 


Explanation 


Directly sets GSWSMATRIX. If you use GsSetRefViewUnit() to determine GSWSMATRIX from the viewpoint 
and the focal point, insufficient precision may cause errors when you move the viewpoint; it is more 
effective to use GsSetViewUnit(). When the GsVIEWUNIT super member is set to anything besides 
WORLD, even if the other parameters remain unchanged, the viewpoint moves if the parent coordinate 
system parameters are changed. In such cases, you must call GsSetViewUnit() for each frame. If 
GsIDMATRIX2 is used as the base matrix, then the aspect ratio of the screen is adjusted automatically. 





Return value 
O, if setting is successful; 1, if unsuccessful. 


Run-Time Library Reference 


HMD Library Functions 17-37 





GsSortUnit 

Allocate an object to the ordering table. 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 

Syntax 

void GsSortUnit( 

GsUNIT *objp, Pointer to an object 

GsOT *otp, Pointer to the OT 

u_short “scratch) Specifies scratch pad address 

Explanation 


Performs perspective transformation and light source calculation on a three dimensional object handled by 
GsUNIT. The rendering command is generated in the packet area specified by GsSetWorkBase(). The 
rendering command generated is then Z-sorted and allocated to the OT displayed by otp. When scratch 
calls the subordinate functions, it is used in the transfer of variables. Usage volume is as follows: 











Table 17-2 
Type Scratch area usage (Unit: Byte) 
Independent polygons 32 
Shared polygons 40 
Fixed division independent triangles 568 
Fixed division independent quadrangles 852 
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GsU_... 

GsSortUnit() primitive driver group (Polygon, Shared Polygon, Image, Ground). 
Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 

Syntax 

u_long *GsU_00......( Polygon primitive driver group 

GsARGUNIT *ap) Start address for arguments transfer area 


u_long *GsU_01...... ( Shared polygon primitive driver group 


GsARGUNIT *ap) Start address for arguments transfer area 
u_long *GsU_02......( Image primitive driver group 

GsARGUNIT *ap) Start address for arguments transfer area 
u_long *GsU_05......( Ground primitive driver group 
GsARGUNIT *ap) Start address for arguments transfer area 
Explanation 


This is the GsSortUnit() primitive driver group. 


When initializing HMD data for use, the GSTYPEUNIT structure type returned by GsScanUnit() must be 
checked, and the primitive driver address must be placed in the pointer. The primitive drivers currently 
supported are listed in the HMD section in the File Formats manual. 


When using a primitive driver which performs division, the number of divisions must be set to the significant 
8 bits of the area in which the primitive index is stored as follows: 


Type 
# of polygons Size 
# of divisions | Primitive index 

















In order to specify the number of divisions, a macro such as the one following is provided in libhmd.h. 








Table 17-3 
Macro #of divisions 
GsUNIT_DIV1 2x2 divisions 
GsUNIT_DIV2 4x4 divisions 
GsUNIT_DIV3 8x8 divisions 
GsUNIT_DIV4 16x16 divisions 
GsUNIT_DIV5 32x82 divisions 





Furthermore, when using automatic division, it is necessary to use GsSetAzwh() and to set the division 
condition for the z value, polygon size, etc. 


Refer to the sample program: (psx\sample\graphics\hmd\pdriver\OO000008.c). 





Return value 
Start address of the next primitive driver. 


See also 
GsSortUnit(), GsScanUnit() 
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GsU_03000000 


HMD animation frame update driver. 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 


Syntax 


u_long *GsU_03000000( 
GsARGUNIT_ANIM “sp) Argument transfer area 


Arguments 


Explanation 


The frame update driver interprets the sequence descriptor and calls the appropriate interpolation function. 
It carries out Sequence jumps, reverses, etc. Since the driver’s internal status is stored in each sequence 
pointer area, real-time control of the sequence is possible if the programmer rewrites this area when 
executing the program. 














For high speed operation, specify scratch pad. The argument information built on sp is as follows: 





primtop 
tag(OT) 


shift(OT) 
OUTP(packet area) 














Animation header size 





Interpolation function 
header 


CONTROL TOP pointer 
PARAMETER TOP pointer 
COORDINATE TOP pointer 
VERTEX TOP pointer 


























Sections except the last two are always set. Since the primitive headers of the other sections are copied as 
is, if the header shape changes, it will be altered. The animation header size contains the amount of 
animation information which is copied to the arguments area. In the case of the above example, 6. 








Refer to the explanation in GSSEQ for details on the sequence pointer. 
The frame update driver is linked to the HMD primitive block PRE-PROCESS. 


GsSortUnit() is called when processing the first primitive block (PRE-PROCESS). The frame update driver 
specifies the sequence descriptor which should be referred to by the sequence pointer. By interpreting that 
sequence pointer the sequence progression is controlled. Finally, the sequence descriptor which refers to 
the key frame performs interpretation, a suitable interpolation driver (GRC FRAME or DST FRAME) is 
attached and called. 











Refer to the sample program, (PS-X/sample/graphics/hmd/pdriver/GsU_OO0000008.c). 





Return value 
The area in which the start address of the next primitive driver is stored. 
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See also 
GsSortUnit(), GsScanUnit() 
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GsU_03000001... 
HMD animation interpolation function (alignment, COORDINATE). 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.0 12/14/98 
Syntax 


int GSU_03000001...( 
GsARGUNIT_ANIM *so) Argument transfer area 


Arguments 


Explanation 
This function is the interpolation driver for parameter interpolation. 


For high-speed operation, use the scratch pad. Information on arguments contained in sp is as follows: 





primtop 
tag(OT) 
shift(OT) 
offset(OT) 
OUTP(packet area) 

















Animation header size 





Interpolation function 
table pointer 


CONTROL TOP pointer 
PARAMETER TOP pointer 
COORDINATE TOP pointer 
VERTEX TOP pointer 


Sequence pointer address 




















Pointer to src parameters 





Pointer to dst parameters 





Write pointer after interpolation 














The parameters in the interpolation function which are always fixed are the last four: 


e Sequence pointer address: Designates the section which rewrites data from the rewrite index after 
interpolation, and the rewrite address. 

e Pointer to src parameter: Pointer which indicates the src keyframe within the parameter section. 

e Pointer to dst parameter: Pointer which indicates the dst keyframe within the parameter section. 

e Pointer which writes after interpolation: There are cases when you wish to retain the parameter value 
after interpolation for the Realtime Motion Switch. The area retained for that purpose is passed as a 
pointer which indicates the keyframe within the parameter section. If O, writing is not performed. 











The interpolation coefficient is calculated from the TFRAME and RFRAME stored in the sequence pointer 
and interpolation is performed. 


If src is O and dst is 1, 1-RFRAME/TFRAME becomes the interpolation coefficient. 





Since the name of the function in the interpolation type indicates the HMD type in interpolation types, refer 
to the HMD format 
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The interpolation algorithm can be one of the following: 


e LINEAR: Interpolate the interval between SRC KEYFRAME and DST KEYFRAME as a straight line. 

e BEZIER: The KEY FRAME has 3 control points. One control point in the DST KEYFRAME and 3 
control points in the SRC KEYFRAME comprise the 4 control points used for BEZIER interpolation. 

e BSPLINE: The KEY FRAME has one control point. SRC-2, SRC-1, SRC, and DST together comprise 
4 control points that are used for BSPLINE interpolation.A WORK area is maintained for the sequence 
history of SRC-2 and SRC-1. The WORK area is set from the START IDX member of the sequence 
pointer. 4 x 32 bits are used in the WORK area. At the start of the sequence, there is no history of 
SRC-2 and SRC-2 so it is necessary to arrange the first 3 key frames so that TFRAME = 0. 











The primitive drivers currently supported by libhmd are listed in the HMD section in the File Formats 
manual. 


Refer to: psx\sample\graphics\hmd\pdriver\O3000001.c, O8000002.c, 03000003.c, 03000010.c, 
03000020.c, 03000030.c 


Return value 
O after normal interpolation. 





If the next key frame is read unconditionally, 1 is returned and in the same frame, the destination key frame 
is once again called back as an argument. This case allows the sequence to instantly advance with 
TFRAME=0. 


See also 
GsU_038000000() 
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GsU_03010110... 


HMD animation interpolation function (general). 


Library Header File Introduced Documentation Date 
libhmd.tib libhmd.h 4.1 12/14/98 
Syntax 


int GsU_03010110...( 
GsARGUNIT_ANIM *so) Argument transfer area 


Arguments 


Explanation 


This function is the generic interpolation driver for parameter interpolation. The numerical values that are 
interpolated can be packaged as 3-element vectors of 8-bits, 16-bits, or 32-bits, or as a scalar. The 
argument area pointer is passed as the argument. The interpolation coefficient is calculated from the 
TFRAME and RFRAME stored in the sequence pointer and interpolation is performed. 





For high-speed operation, use the scratch pad. Information on arguments contained in sp is as follows: 





primtop 
tag(OT) 
shift(OT) 
offset(OT) 
OUTP(packet area) 

















Animation header size 





Interpolation function 
table ponter 


CONTROL TOP pointer 
PARAMETER TOP pointer 
COORDINATE TOP pointer 
VERTEX TOP pointer 


Sequence pointer address 




















Pointer to src parameters 





Pointer to dst parameters 











Write pointer after interpolation 








The parameters in the interpolation function which are always fixed are the last four. 


e Sequence pointer address: Designates the section which rewrites data from the rewrite index after 
interpolation, and the rewrite address. 

e Pointer to src parameter: Pointer which indicates the src keyframe within the parameter section. 

e Pointer to dst parameter: Pointer which indicates the dst keyframe within the parameter section. 

e Pointer which writes after interpolation: There are cases when you wish to retain the parameter value 
after interpolation for the Realtime Motion Switch. The area retained for that purpose is passed as a 
pointer which indicates the keyframe within the parameter section. If O, writing is not performed. 


If src is O and dst is 1, 1-RFRAME/TFRAME becomes the interpolation coefficient. 














Run-Time Library Reference 


17-44 HMD Library Functions 





Since the name of the function in the interpolation type indicates the HMD type in interpolation types, refer 
to the HMD format 


The interpolation algorithm can be either LINEAR, BEZIER, or BSPLINE. 


e LINEAR: Interpolate the interval between SRC KEYFRAME and DST KEYFRAME as a straight line. 

e BEZIER: The KEY FRAME has 8 control points. One control point in the DST KEYFRAME and 3 
control points in the SRC KEYFRAME comprise the 4 control points used for BEZIER interpolation. 

e BSPLINE: The KEY FRAME has one control point. SRC-2, SRC-1, SRC, and DST together comprise 4 
control points that are used for BSPLINE interpolation. 


A WORK area is maintained for the sequence history of SRC-2 and SRC-1. The WORK area is set from 
the START IDX member of the sequence pointer. 4 x 32 bits are used in the WORK area. At the start 
of the sequence, there is no history of SRC-2 and SRC-2 so it is necessary to arrange the first 3 key 
frames so that TFRAME = 0. 


The primitive drivers currently supported by libhmd are listed in the HMD section in the File Formats 
manual. 


Refer to: psx\sample\graphics\hmd\pdriver\O3000001.c, O8000002.c, 03000003.c, 03000010.c, 
03000020.c, 03000030.c 














Return value 
O after normal interpolation. 
If the next key frame is read unconditionally, 1 is returned and in the same frame, the destination key frame 


is once again called back as an argument. This case allows the sequence to instantly advance with 
TFRAME=0. 





See also 
GsU_038000000() 
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GsU_040100... 
HMD MIMe driver. 


Library Header File Introduced Documentation Date 
libhmd.lib libhmd.h 4.0 12/14/98 

Syntax 

u_long *GsU_040100...( 

GsARGUNIT *ap) Start address of argument transfer area. For high-speed operation, use 


the scratch pad. 


Explanation 


This function is the driver group for MIMe animation from the HMD library. Although the ap argument is 
GsARGUNIT type, it is handled internally as a different type. MIMe category drivers currently supported by 
libghmd are as follows: 


Table 17-4 


Driver name Type name macro ap processing type Explanation 
GsU_04010010 GsJntAxesMIMe GsARGUNIT_JntMIMe Axis interpolation 
joint mime 
GsU_04010018 GsRstJUntAxesMIMe GsARGUNIT_RstUntMIMe Axis interpolation 
joint mime reset 
GsU_0401001 1 GsJntRPYMIMe GsARGUNIT_JntMIMe RPY value 
interpolation joint 
mime 
GsU_04010019 GsRstUntRPYMIMe GsARGUNIT_RstJntMIMe RPY value 
interpolation joint 























mime reset 
GsU_04010020 GsVtxMIMe GsARGUNIT_VNMIMe Vertex mime 
GsU_04010021 GsNrmMI|Me GsARGUNIT_VNMIMe Normal mime 
GsU_04010028 GsRstVtxMIMe (*) GsARGUNIT_RstVNMIMe Vertex mime reset 
GsU_04010029 GsRstNrmMIMe (*) GsARGUNIT_RstVNMIMe Normal mime reset 





(*) Initialization is needed for GsInitRstVtxMIMe, GslnitRstNrmMIMe 


Return value 


Start address of next primitive driver. 
Refer to sample program (psx\sample\grapihcs\hmd\pdriver\OO000008.c). 


See also 


GsARGUNIT_JntMIMe(), GSARGUNIT_RstJntMIMe(), GSARGUNIT_VNMIMe(), GSARGUNIT_RstVNMIMe(), 
GslnitRstNrmMIMe(, GsInitRstVtxMIMe() 
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McxAlllnfo 

Get all PDA information (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxAllinfo ( 

int port, Port number (see Table 18-1) 

unsigned char *state) Pointer to buffer for storing the results of reading all PDA information. The 


buffer size must be 18 bytes. 


Explanation 
Port numbers are as follows: 


Table 18-1: Port numbers 


Port 1 Port 2 
Direct connect Ox00 0x10 
Multitap A Ox00 0x10 
Multitap B 0x01 0x11 
Multitap C 0x02 0x12 
Multitap D 0x03 0x13 


With 1 Vsync this function can simultaneously obtain the block number of the header which contains an 
executing PDA application, the PDA application's flash memory priority write settings, the state of the PDA's 
current capacity controls, the serial number, and time and date information. 


The contents stored in state are as follows: 


Table 18-2 


Q 
(2) 
(o) 
LA 


Contents 

Executing PDA application number (LSB) 
Executing PDA application number (MSB) 
Speaker disabled 

IR communication disabled 

PDA serial number (LSB) 

PDA serial number (1) 

PDA serial number (2) 

PDA serial number (MSB) 

Real-time clock (100 years) 

Real-time clock (year) 

Real-time clock (month) 

Real-time clock (day) 

Real-time clock (day of the week) 
Real-time clock (hours) 

Real-time clock (minutes) 

Real-time clock (seconds) 

PDA application's flash write priority 
disabled 

LED disabled 
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This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has been completed. Use McxSync() to check for process completion. 
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Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


Note: It is impossible to check for duplicate registrations between an McxXXX() function and functions like 
_card_xxx() and MemCardxxx(). When a request is made to register an McxXXX() function after these other 
processes have already been registered, the return value will still be "Registration accepted", even though 
registration will not be guaranteed. Consequently, it is best to avoid simultaneous registration between an 
McxxXXX() function and _card_xxx() or MemCardxxx() functions. Likewise, if registration of an McxXXX() 
function is requested while executing read(), write), delete(), etc., after a Memory Card file has been 
opened, the return value will still be "Registration accepted", even though registration will not be 
guaranteed. Again, it is best to avoid these cases. 








See also 
McxGetApl(), McxCurrCtrl(), McxFlashAcs(), McxGetSerial(), McxGetTime(), McxSync() 
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McxCardType 

Probe PDA connection status (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxCardType ( 

int port) Port number (see Table 18-1) 

Explanation 





This function is used to check for the presence of a PDA. The value of the result returned from McxSync() is 
used to make the determination. Once card connection is confirmed using a function such as 
MemCardAccept() or _card_info(), McxCardType() can be called. An McxErrSuccess result would mean 
that a PDA was detected, and an McxErrinvalid would mean that a Memory Card was detected. However, if 
the Memory Card connection is determined with McxErrlnvalid, the operation should be retried to be 
certain. 


Table 18-3: Result value and connection status of McxSync() 


Value Macro Result 

0 McxErrSuccess Normal termination 

1 McxErrNoCard Neither PDA nor Memory 
Card inserted 

2 McxErrlnvalid Communication failure 

3 McxErrNewCard Normal termination (card 


has been swapped) 


This function only registers a process. Check the contents of the buffer in which the results are stored after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxSync() 
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McxCurrCtrl 

Control current capacity (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxCurrCtrl ( 

int port, Port number (see Table 18-1) 

int sound, 1: Disable speaker, 0: Enable speaker 

int infred, 1: Disable transmit, 0: Enable transmit 

int /ed) 1: Disable LED, 0: Enable LED 


(The meaning of all other values is the same as 1: disabled) 





Explanation 

Limits the speaker, IR transmission and LED among PDA functions. This is necessary because there is an 
upper limit to the current that the PlayStation® can supply to the front terminals. Immediately after the PDA 
is inserted into the PlayStation, all become disabled by default. 





The current consumed by each module is indicated in the following table. Since the maximum current that 
can be supplied by the PlayStation from the two ports totals 160mA, do not exceed this value. 


Table 18-4 
Module name Current consumed 
CPU chip 10mA 
IR module transmission-side 70MA 
Speaker 20mA 
LED 10mA 


Before attempting to use the aforementioned three functions in a PDA application, use Get PDA Status (swi 
6) to check the permission status of each function. (For a description of the required processing, please 
refer to the PDA Kernel Specification document.) 








Call McxAlllnfo() to check the restrictions on available functions. 
This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxAlllnfo(), McxSync() 
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McxExecApl 
Execute a PDA application (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 2/24/99 
Syntax 
int McxExecApl ( 
int port, Port number (see Table 18-1) 
int aplno, Block number of header which contains the desired PDA application to 
execute. 
(Process registration fails if a non-negative value other than 0-15 is 
specified.) 
long arg) Argument passed to the application to be started. 
Explanation 





The PDA application with the specified header block number is executed. If the specified block number is 
not a header block of a PDA application, proper PDA operation cannot be guaranteed. In order to confirm 
that the target application has started, check the number of the currently executing PDA application by 
calling McxGetApl() or McxAlllnfo(). 


When this function is called from the PDA application, the "PDA Application Exited" flag (bit 11) from the 
result of Get PDA Status (swi 6) conveys a request to terminate the application from the PlayStation (this 
flag should be checked periodically). Please see the PDA Kernel Specification document for more 
information on processing required by the PDA application when the application terminates. 











This function is used to make a request to terminate the currently executing PDA application. However, if 
the currently executing application refuses to terminate, McxGetApl() should be used, after calling 
McxExecApl(), to ensure that the PDA application has switched. 


This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed, or a value other than 0-15 is specified as the block number.) 


See note on page 18-4 for more information. 


See also 
McxGetApl(), McxAlllnfo(), McxSync() 
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McxExecFlag 

Set the PDA application / data ID flag (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 2/24/99 

Syntax 

int McxExecFlag ( 

int port, Port number (see Table 18-1) 

int block, Block number of the header which contains the desired file for which you 


wish to set the PDA application flag (The result of dividing the DIRENTRY 
member head by 64. If the specified value is other than 1-15, process 
registration fails.) 

int exec) 1: PDA application flag set, O: Flag cancelled (All other values, same as 1) 





Explanation 

Called and set when downloading a PDA application to the PDA. (May be called any time after the file is 
created.) The PDA application flag is set to O when a Memory Card file copy is performed from the 
PlayStation Memory Card set-up screen, etc. 


By referring to the PDA kernel software interrupt (swi 24), the value of the PDA application flag can be used 
to determine whether or not the PDA application that is executing is an original download or one copied 
from another PDA and Memory Card. 


This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


In libmex, issuing only McxExecFlag() will not provide an McxSync() result of McxErrlnvalid for a Memory 
Card. If successful, the PDA application flag will also be set for the corresponding section of the Memory 
Card which issued this instruction. 





If the result from McxSync() is McxErrNewCard, processing will be interrupted for McxExecFlag(). Unverified 
flags should first be cleared using MemCardAccept() and _card_clear(), then process registration should be 
performed again. 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed, or a value other than 1-15 was specified for the block number.) 


See note on page 18-4 for more information. 


See also 
McxSync() 
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McxFlashAcs 

Set a PDA application's flash memory write priority (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxFlashAcs ( 

int port, Port number (see Table 18-1) 

int mode) 0: Allows communication with the PlayStation to be temporarily suspended 


so that the PDA application can write to the flash memory. 
1: Disables writing to the flash memory. 
(The meaning of all other values is the same as 1: disabled) 





Explanation 

While a PDA application is writing to the flash memory, performing communication with the PlayStation can 
lead to processing load and access contention problems. So, when a PDA application is able to write to 
the flash memory, the PlayStation-side program will first determine whether or not communication with the 
PDA might fail, then this function can be used to allow the flash memory to be written. 


The default is to not allow the PDA application to write to the flash memory. In other words, communication 
with the PlayStation has priority over writing of the flash memory. 





Communication with the PDA is sometimes interrupted while flash memory writing is enabled. Therefore, it 
sometimes is necessary to perform a retry in order to communicate reliably. Communication with the PDA 
can be interrupted in the following cases: 

When _card_XXX() is used and the HwCARD | EvSpTIMOUT event is generated. 

When MemCardxxXX() is used and McxErrCardNotExist is returned in “result of MemCardSync(). 

When McxxXXX() is used and McxErrNoCard is returned in *result of McxSync(). 





Call McxAlllnfo() to check the restrictions on available functions. 


Before attempting to write to the flash memory from a PDA application, use Get PDA Status (swi 6) to 
check the flash memory write enable status. (For a description of the required processing, please refer to 
the PDA Kernel Specification document.) 





This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxAlllnfo(), McxSync() 
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McxGetApl 

Obtain the block number where the executing PDA application is stored (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxGetApl ( 

int port, Port number (see Table 18-1) 

int *aplno) Pointer to a memory location which returns the block number where the 


executing PDA application is stored. 


Explanation 


The block number of the header where the currently executing PDA application is stored is placed in the 
memory location pointed to by apino. 





If the currently executing application is the "Start-up Application", *apino returns O. 


If the currently executing application is other than the "Start-up Application", *ao/no returns the block 
number of the header where the application is stored. 





When McxAllinfo() is used, the executing application number together with other information can be 
obtained during a single frame. 





This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxExecApl(), McxAlllnfo(, McxSync() 
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McxGetMem 

Read the contents of PDA memory (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxGetMem ( 

int port, Port number (see Table 18-1) 

unsigned char *data, Buffer for storing PDA memory read data 

unsigned start, Read start address 

unsigned /en) Read size (bytes), (128 bytes max.) 

Explanation 





The specified number of bytes of PDA memory are read from the specified start address and placed in the 
buffer pointed to by data. 


Process registration fails if the read size exceeds 128 bytes. Registration also fails when the read range 
extends outside the areas shown below. Note: if an attempt is made to access address 0x2****** without 
specifying virtual flash memory, a bus error will be generated by the PDA. 





Readable areas: 


OxO****KRK, Ox2*xx*xee, Ox4*exeeK, OxO***KRK, OxQxxxxxx* 
OxA*** ke, OxBe****x, OxC*eeeRK, OxD****** 


(* = an arbitrary hex value) 





This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 
O: Process registration failed. (An attempt was made to register a new process before the previously 


registered process completed, or the read size exceeded 128 bytes. Also fails when an attempt is made to 
access an unavailable area of memory.) 








See note on page 18-4 for more information. 


See also 
McxSetMem(), McxSync() 
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McxGetSerial 

Get the PDA’s serial number (process registration) 
Library Header File Introduced Documentation Date 
liomcx.lib liomcx.h 4.4 12/14/98 

Syntax 

int McxGetSerial ( 

int port, Port number (see Table 18-1) 

unsigned long *seria/) Pointer to a memory location that will contain the obtained serial number 

Explanation 


Gets the serial number of the PDA. 


The serial number, together with other information, can also be obtained using McxAlllnfo(). 





This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxAlllnfo(), McxGetMem(), McxSync() 
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McxGetTime 

Get the date and time (process registration) 
Library Header File Introduced Documentation Date 
liomex. lib libmcx.h 4.4 12/14/98 

Syntax 

int McxGetTime ( 

int port, Port number (see Table 18-1) 

unsigned char “time) Buffer for storing the date and time (8 bytes) 

Explanation 


Obtains the date and time from the PDA's real-time clock. The contents of the buffer are shown below. 
Information other than day of the week are returned as BCD values. 





Table 18-5 


[ofset |O Ji dl? 38 





Contents 100 Year Month | Date Day of | Hr. Min. Sec. 
years week 


The day of the week values returned in offset 4 are: 


Table 18-6 
time|4] pO. Jt SS 
Day of week 


This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 





Date and time information can be obtained, together with other information, using McxAlllnfo(). 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxAlllnfo(), McxSync() 
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McxGetUIFS 

Get user interface status (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxGetUIFS ( 

int port, Port number (see Table 18-1) 

unsigned char “data) Buffer for storing user interface status (8 bytes) 

Explanation 


Obtains user interface status from the PDA. The contents of the buffer are shown below. 











Table 18-7 
Offset Contents 
O Alarm time (minutes) 
1 Alarm time (hours) 
2 (bit)7 RTC set 
(bit)6-4 Area code 
(bit)3-2 Speaker volume 
(bit)1 Key lock 
(bit)O Alarm 
3 Unused 
4 Font data start address (LSB) 
5 Font data start address (MSB) 
6 Unused 
7 Unused 
e Alarm time of day: 2 BCD digits each. 
e RTC set: O: RTC is unset (data invalid) after reset, 1: RTC set (data valid) 
e Area code: 0: Japan, 1: North America, 2: Europe 
e Speaker volume: O: loud, 1: soft, 2: off 
e Key lock: 0: unlocked, 1: locked 
e Alarm: O: off, 1: on 
e Font data start address: Address relative to Ox4000000 


This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxSetUIFS(), McxSync() 
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McxHideTrans 

Hide the "data transfer" display (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 2/24/99 

Syntax 

int McxHideTrans ( 

int port) Port number (see Table 18-1) 

Explanation 


Hides the "data transfer" display on the LCD screen made visible by McxShowTrans(). 





When this function is called, a file transfer control callback is generated from the PDA kernel to the currently 
executing PDA application. This callback, previously registered for "start/stop the data transfer display" 
using the PDA's "set user callback (swi 1)" terminates the data transfer display on the LCD screen of the 
PDA. (For a description of the required processing, please refer to the PDA Kernel Specification document.) 





This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxShowTrans(), McxSync() 
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McxReadDev 

Read from the PDA device (process registration) 
Library Header File Introduced Documentation Date 
liomex. lib libmcx.h 4.4 12/14/98 

Syntax 

int McxReadDev ( 

int port, Port number (see Table 18-1) 

int dev, Called device number (Reserved devices: 0: RTC read/write, 1: PDA memory 





read/write, 2: user interface status read/write) 
unsigned char “param, Parameter passed to device 
unsigned char *data) Data read from device 


Explanation 

Performs a read from a user-defined device or from a reserved device provided on the PDA. In order read 
from a user-defined device, it is necessary to create a subroutine as specified in 
\pdadoc\doc\jp\word\pda\kernel.doc (Kernel Service Overview: Communication with the PlayStation : 
Device Entry Callbacks), then enter it in the device entry table in the Memory Card file header. 














This function performs process registration only. The contents of the result buffer can be used after 
confirming that the process has completed. Use McxSync() to check for process completion. 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 





See note on page 18-4 for more information. 


See also 
McxWriteDev(), McxSync() 
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PDA Library Functions 


McxSetLED 

Switch the LED on/off (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxSetLED ( 

int port, Port number (see Table 18-1) 

int mode) O: Turn LED off, other values: Turn LED on 

Explanation 

Turns the LED on and off. 


McxGetMem() and McxSetMem() can be used to check/set the on/off state of an LED, by directly accessing 
PIOO and PIO1. 


This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 

Return value 

1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxGetMem(), McxSetMem(), McxSync() 
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18-18 PDA Library Functions 


McxSetMem 
Update the contents of PDA memory (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 03/06/00 
Syntax 
int McxSetMem ( 
int port, Port number (see Table 18-1) 
unsigned char “data, Buffer containing the data to be written to PDA memory 
unsigned start, Write start address 
unsigned /en) Write size (bytes), (128 bytes max.) 
Explanation 


Overwrites the specified number of bytes of PDA memory starting at the specified address. Process 
registration fails if the write size exceeds 128 bytes. Registration also fails when the write range extends 
outside the areas shown below. 





Writeable areas: 
Ox Ot e eee, OxXO ee ee ee, OxA****x** 


KKK KKK KKK KKK KKKKKK 
OxB , Oxc , OxD 


(* = arbitrary hex value) 


This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 
O: Process registration failed. (An attempt was made to register a new process before the previously 


registered process completed, or the write size exceeded 128 bytes. Also fails when an attempt is made to 
access an unavailable area of memory.) 














See note on page 18-4 for more information. 


See also 
McxGetMem(), McxSync() 
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PDA Library Functions 


McxSetTime 

Set the date and time (process registration) 
Library Header File Introduced Documentation Date 
liomex. lib libmcx.h 4.4 12/14/98 

Syntax 

int McxSetTime ( 

int port, Port number (see Table 18-1) 

unsigned char “time) Buffer which contains the date and time to be set (8 bytes) 

Explanation 


Sets the date and time in the PDA's real-time clock. 


In order to set the real-time clock, 150 ms (worst case) are required after communication with the PDA is 
completed. During this interval, it is not possible to communicate with the PDA. Note that, if an attempt is 
made to communicate with the PDA during this time, McxSync() will return the McxErrNoCard (Memory 
Card not inserted) result, even though the PDA is inserted in the Memory Card slot. 





The buffer contents are shown below. Information other than day of the week are returned as BCD values. 


Table 18-8 


[Offset Jo Ji | C SG 





Contents 100 Year —— sate Day of | Hr. Sec. 
years week 


The relationship between the day of the week and the value returned in offset 4 is as follows: 


Table 18-9 


im [po Hda ea B 


Day of Mon Tue Wed CE —— 
week 





This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxGetTime(), McxSync() 
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18-20 PDA Library Functions 


McxSetUIFS 

Set user interface status (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxSetUIFS ( 

int port, Port number (see Table 18-1) 

unsigned char “data) Buffer which contains the specified user interface status (8 bytes) 

Explanation 


Sets the PDA’s user interface status. The contents of the buffer are shown below. 











Table 18-10 
Offset Contents 
O Alarm time (minutes) 
1 Alarm time (hours) 
2 (bit)7 RTC set 
(bit)6-4 Area code 
(bit)8-2 Speaker volume 
(bit)1 Key lock 
(bit)O Alarm 
3 Unused 
4 Font data start address (LSB) 
5 Font data start address (MSB) 
6 Unused 
7 Unused 
e Alarm time of day: 2 BCD digits each. 
e RTC set: O: RTC is unset (data invalid) after reset, 1: RTC set (data valid) 
e Area code: 0: Japan, 1: North America, 2: Europe 
e Speaker volume: O: loud, 1: soft, 2: off 
e Key lock: 0: unlocked, 1: locked 
e Alarm: O: off, 1: on 
e Font data start address: Address relative to Ox4000000 


This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxGetUIFS(), McxSync() 
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PDA Library Functions 


McxShowTrans 

Show the "data transfer" display (process registration) 
Library Header File Introduced Documentation Date 
liomex. lib libmcx.h 4.4 2/24/99 

Syntax 

int McxShowTrans ( 

int port, Port number (see Table 18-1) 

int dir, Transfer direction. 0: PDA --> PS, other values: PS --> PDA 

int timeout) Time until the display is cleared if a request to hide the "data transfer" display 


is not received. (1 second units in the activated application) 


Explanation 

In order to avoid alternate sector processing when saving a PDA application file or a data file that contains a 
PDA file list icon (i.e., so that the PDA program can be saved to consecutive memory), call this function 
before opening the file. 





Since MemCardFormat() and _card_format() also initialize alternate sectors, do not call McxShowTrans() 
when formatting the Memory Card (formatting will fail without initializing the alternate sectors). 


When this function is called, a file transfer control callback is generated from the PDA kernel to the currently 
executing PDA application. This callback, previously registered for "start/stop the data transfer display" 
using the PDA's "set user callback (swi 1)" terminates the data transfer display on the LCD screen of the 
PDA. 


The timeout setting allows the PDA application itself to hide the "data transfer" display, if the PlayStation is 
reset unexpectedly, etc. Normally, McxHideTrans() is called to hide the display after the file transfer has 
completed. 





(For a description of the required processing, please refer to the PDA Kernel Specification document.) 
This function performs process registration only. Before calling another process registration function or a 
Memory Card access function, check for process completion using McxSync(). 


Return value 
1: Process registration was accepted. 


O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 





See note on page 18-4 for more information. 


See also 
McxHideTrans(), McxSync() 
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18-22 PDA Library Functions 


McxStartCom 

Start the PDA system 
Library Header File Introduced Documentation Date 
liomcx.lib liomcx.h 4.4 12/14/98 

Syntax 


void McxStartCom(voic) 


Explanation 


Starts the PDA system. Enables PDA processing-related interrupts, and allows each of the PDA's process 
registration functions to be used. The PDA library does not contain any initialization functions (like InitCARD() 
or MemCardlnit(). Instead, the PDA system is activated simply by calling McxStartCom(). 


McxStartCom() has a restriction in that it must be called in a specific sequence relative to other functions. 





For functions connected with arrows, the function at the starting point of the arrows must be called first. 






StartCARD() 
McxStartCom() 
PadInitDirect(),PadInitMtap() 


PadStartCom() 












StartPAD() 





A standard sequence would be as follows. 


PadInit (); 
InitPAD (); 
StartPAD(); 
InitCARD (); 
StartCARD (); 
McxStartCom(); 
PadInitDirect (); 
PadStartCom() ; 


However, the following three sets of function pairs cannot be called simultaneously: 

[PadInit()], [InitPAD(),StartPAD(],[PadInitDirect(), PadStartCom(]. 

An appropriate set from the three sets should be selected when writing programs. 

MemCardlnit() and MemCardStart() can be replaced with InitCARD() and StartCARD)(). lnitPAD() and 
StartPAD() can be replaced with InitTAP() and StartTAP() or InitGun() and StartGUN(. 


See also 
McxStopCom() 
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PDA Library Functions 


McxStopCom 

Stop the PDA system 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 


void McxStopCom(voia) 


Explanation 

Halts PDA system-related interrupts and shuts down the PDA system. 

The McxStartCom() and McxStopCom() pair of start/stop functions must be correctly nested with the calling 
sequence of the start/stop function pairs determined in McxStartCom(). 


See also 
McxStartCom() 
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18-24 PDA Library Functions 


McxSync 


Confirm the completion of a registered process 





Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 2/24/99 

Syntax 

int McxSync ( 

int mode, O: Wait until the registered process completes. 1: Check the current state 

and return it immediately. 

long *cmd, Completed command number 

long *result) Registered process result 

Explanation 


Use McxAlllnfo(), McxCurrCtrl(), etc., to check the progress of a registered process. The command number 
of the executing or completed process is returned in cmd. The contents of cmd are shown in the following 








table. 


Table 18-11 
Value 


-OONDORWN — 


i 
OANDAKRWBN+-O 


A ob 1 


k 


4 


i 





i 


Macro 
McxFuncGetApl 
McxFuncExecApl 
McxFuncGetTime 
McxFuncGetMem 
McxFuncSetMem 
McxFuncShowTrans 
McxFuncHideTrans 
McxFuncCurrCtrl 
McxFuncSetLED 
McxFuncGetSerial 
McxFuncExecFlag 
McxFuncAlllnfo 
McxFuncFlashAcs 
McxFuncReadDev 
McxFuncWriteDev 
McexFuncGetUIFS 
McexFuncSetUIFS 
McxFuncSetTime 
McxFuncCardType 


The processing result is returned in "result." 


Table 18-12 


Value 
O 
1 


2 
3 


Return value 
Table 18-13 


Value 
O 

1 

-1 
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Macro 
McxErrSuccess 
McxErrNoCard 


McxErrlnvalid 
McxErrNewCard 


Macro 
McxSyncRun 
McxSyncFin 
McxSyncNone 
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Function 
McxGetApl() 
McxExecApl() 
McxGetTime() 
McxGetMem() 
McxSetMem() 
McxShowTrans() 
McxHideTrans() 
McxCurrCtrl() 
McxSetLED() 
McxGetSerial() 
McxExecFlag() 
McxAlllnfo() 
McxFlashAcs() 
McxReadDev() 
McxWriteDev() 
McxGetUIFS() 
McxSetUIFS() 
McxSetTime() 
McxCardType() 


Result 
Normal termination 


Neither PDA nor Memory 


Card inserted 
Communication failure 


Normal termination (card 


has been swapped) 


Process state 
Processing 

Process complete 
Process unregistered 
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See also 


McxGetApl(), McxExecApl(),McxGetTime(), McxGetMem(), McxSetMem(), McxShowTrans(), McxHideTrans(), 
MexCurrCtri(), McxFlashAcs(), McxSetLED(), McxGetSerial(), McxExecFlag(), McxAllllnfo() 
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McxWriteDev 

Write to a PDA device (process registration) 
Library Header File Introduced Documentation Date 
libmcx.lib libmcx.h 4.4 12/14/98 

Syntax 

int McxReadDev ( 

int port, Port number (see Table 18-1) 

int dev, Called device number (Reserved devices: 0: RTC read/write, 1: PDA memory 





read/write, 2: user interface status read/write) 
unsigned char “param, Parameter passed to device 
unsigned char *data) Data written to device 


Explanation 


Performs a write to a user-defined device or to a reserved device provided on the PDA. In order to write to a 
user-defined device, it is necessary to create a subroutine as specified in the PDA Kernel Specification 
document (Kernel! Services Overview - Device Entry Callback section of “Communication with the 
PlayStation”), then enter it in the device entry table in the Memory Card file header. 








This function only registers a process. Check the contents of the buffer in which the results are stored after 
confirming that the process has completed. Use McxSync() to check for process completion. 





Return value 
1: Process registration was accepted. 





O: Process registration failed. (An attempt was made to register a new process before the previously 
registered process completed.) 


See note on page 18-4 for more information. 


See also 
McxReadDev(), McxSync() 
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Chapter 19:Memory Card GUI Module (mcgui) 


Table of Contents 


Structures 
McGuiEnv 
sMcGuiBg 
sMcGuiCards 
sMcGuiController 
sMcGuiCursor 
sMcGuiSnd 
sMcGuiTexture 
Functions 
McGuiLoad 
McGuiSave 
McGuiSetExternalFont 
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McGuiEnv 
Memory Card GUI module structure 
Module Header File Introduced Documentation Date 
mcgui. obj megui.h 4.4 12/14/98 
Structure 
struct McGuiEnv { 
sMcGuiCards cards; Memory Card data structure 
sMcGuiBg bg; BG data structure 
sMcGuiController controller; Controller-related data structure 
sMcGuiSnd sound; BGM and sound effect data structure 
sMcGuiTexture texture; Texture data structure 
sMcGuiCursor cursor; Cursor data structure 
} 
Explanation 


This is the main structure used by the memory card GUI module. 


Each member is a separate structure. 
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19-4 Memory Card GUI Module Structures 


sMcGuiBg 


BG data structure 


Module Header File Introduced Documentation Date 
mcegui. obj megui.h 4.4 12/14/98 


Structure 


struct sMcGuiBg { 
short mode; BG mode 
0: Scroll mode Use the internal 64 X 64 tiled-texture scroll mode 
1: Use the texture specified by the still-image mode (timadr) 
signed char scrol/Direct; Scroll direction (valid when BG mode = 0) 
O: up, 1: top left, 2: left, 3: bottom left 4: down, 5: bottom right, 6: 
right, 7: top right 





signed char scrol/Speed; Scroll speed (valid when BG mode = 0) 
0: Stopped 1: 1/60 sec., 2: 1/80 sec., 3: 1/20 sec. 
u_long* timadr; Header address of TIM data for BG (valid when BG mode = 1) 
i 
Explanation 


Part of the McGuiEnv structure. 
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Memory Card GUI Module Structures 


sMcGuiC ards 
Memory Card data structure 
Module Header File Introduced Documentation Date 
mcqgui.obj mcgui.h 4.4 3/6/00 
Structure 
struct sMcGuiCards { 
char file[21]; File name Use only ASCII except for 0x00, 0x2a(*), and 0x3f(? ). The 
string is terminated by 0x00. 
char title[65]; Document name Only full-size 32 characters of (SJ IS) non-kanji and 


level-1 kanji. However, 0x84bf to 0x889e cannot be used. The string 
is terminated by 0x00. 


char frame; Number of icon images (automatically animated) 1-3 
char block; Number of game data blocks (1-15) 
u_long* iconAddr; TIM data header address for icon image 
When this is 0 and McGuiLoad has been executed, icon data is not 
obtained. 
u_long* dataAddr; Header Address of game data 
long dataB ytes; Number of game data bytes (128-byte units) 
} 
Explanation 


This structure holds information used for loading and saving game data. 


Part of the McGuiEnv structure. 


CONFIDENTIAL Run-Time Library Reference 


19-5 


19-6 Memory Card GUI Module Structures 


sMcGuiController 
Controller data structure 
Module Header File 
mcegui. obj mcegui.h 
Structure 


struct sMcGuiController { 
volatile u_char* buf[2]; 
struct { 
int flag; 
u_long BUTTON_OK; 
u_long BUTTON_CANCEL; 
} type7; 
struct { 
int flag; 
u_long BUTTON_OK; 
u_long BUTTON_CANCEL; 
} type2; 
struct { 
int flag; 
u_long BUTTON_OK; 
u_long BUTTON_CANCEL; 
} types; 
struct { 
int flag; 
u_long BUTTON_OK; 
u_long BUTTON_CANCEL; 
} type4; 


Explanation 


Introduced Documentation Date 


4.4 12/14/98 


Controller's receive data buffer 


Default controller 


Mouse 


Analog joystick, DUAL SHOCK 


NeGcon 


This structure holds controller information. It is part of the McGuiEnv structure. 





Set the flag members of the supported controller tyoes to 1, and set the respective button codes in the 
BUTTON_OK/BUTTON_CANCEL fields. Set the flag members of unsupported controller types to O. 
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sMcGuiCursor 
Cursor data structure 
Module Header File Introduced Documentation Date 
mcegui. obj megui.h 4.4 12/14/98 
Structure 
struct sMcGuiCursor { 
char type; Cursor shape (not supported) 
u_char r; Color code (0-255) 
u_char g; Color code (0-255) 
u_char b; Color code (0-255) 
} 
Explanation 


This structure sets the color and shape of the menu cursor. It is part of the McGuiEnv structure. 


Note: type is currently not supported. 
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19-8 Memory Card GUI Module Structures 


sMcGuiSnd 


BGM and sound effects data structure 


Module Header File Introduced Documentation Date 
mcegui. obj mcegui.h 4.4 12/14/98 
Structure 
struct sMcGuiSnd { 
int MVOL; Main volume (0-127) 


int isReverb; O: reverb OFF, 1: reverb ON 

int reverb Type; Reverb type 

int reverbDepth; Reverb depth (0-127) 

struct { 
int isbgm; 0: no BGM, 1:BGM 
u_long* seq; Header address of SEQ data 
u_long* vh; Header address of VH data for SEQ 
u_long* vb; Header address of VB data for SEQ 
int SVOL; SEQ volume (0-127) 

}bgm; 

struct { 
int isse; O: no sound effects, 1: sound effects 
u_long* vh; Header address of VH data for SE 
u_long* vb; Header address of VB data for SE 
int vol; Sound effects volume 
int prog; Sound effects program number 
int TONE_Ok; Tone number of confirmation/execution tone 


int TONE_CANCEL; 
int TONE_CURSOR; 
int TONE_ERROR; 

} se; 


Tone number of CANCEL tone 
Tone number during cursor operation 
Tone number of error tone 


} 
Explanation 


This structure contains information about the BGM that plays on the Memory Card screen and the sound 
effect that is produced when the cursor is moved, etc. 
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sMcGuiTexture 
Texture data structure 


Module Header File Introduced Documentation Date 
mcegui. obj mcegui.h 4.4 12/14/98 


Structure 


struct sMcGuiTexture { 
u_long* addr; Header address of TIM data 
} 


Explanation 
This structure specifies the texture data used internally by the module. It is part of the McGuiEnv structure. 


Note: For format information, refer to the Run-time Library Overview. 
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19-10 Memory Card GUI Module Functions 


McGuiLoad 


Load game data 


Module Header File Introduced Documentation Date 
mcgui. obj megui.h 4.4 12/14/98 


Syntax 


int McGuiLoad( 
McGuiEnv * env) Memory Card GUI module structure 


Explanation 
Invokes the load operation of the Memory Card screen. 


Terminates when the load has completed or when the cancel button is clicked on the Slot Selection screen. 





Return value 
1 after the load operation completes 


O if the cancel button was used to terminate the load 


-1 if an invalid value is specified in the McGuiEnv structure 
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McGuiSave 


Save game data 


Module Header File Introduced Documentation Date 
mcegui. obj megui.h 4.4 12/14/98 


Syntax 

int McGuiSave( 

McGuiEnv *env) Memory Card GUI module structure 
Explanation 

Invokes the save operation of the Memory Card screen. 








Terminates when the save is completed or when the cancel button is clicked on the Slot Selection screen. 


Return value 
1 after the save operation completes. 


O if the cancel button was used to terminate the save. 


-1 if an invalid value is specified in the McGuiEnv structure. 
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McGuiSetE xternalFont 
Sets language mode 
Module Header File Introduced Documentation Date 
mcgui.obj mcgui.h 45 3/6/00 
Syntax 
int McGuiSetE xternalF ont( 
McGuiEnv *env, Memory Card GUI module structure 
int mode) Language mode 
0: J apanese 
1: English 
2: French 
3: German 
4: Italian 
5: Spanish 
Explanation 


Switches the messages used on the Memory Card screen to each language. 
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DECDCTENYV (lippress), 6-3 
DIRENTRY (lbapi), 1-3 
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EXEC (libapi), 1-5 
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7 1-1 
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UN 
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GSBG (libgs), 1-3 
GsBOXF (libgs), 1-4 

GsCELL (libgs), 1-5 
GsCOORD2PARAM (libgs), 1-6 
GsCOORDINATE? (libgs), 1-7 
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GsDOBJZ2 (libgs), 1-8 
GsDOBJS3 (libgs), 1-10 
GsDOBJ5 (libgs), 1-11 
GsF_LIGHT (libgs), 1-14 
GsFOGPARAM (libgs), 1-13 
GsGLINE (libgs), 1-15 
GsIMAGE (libgs), 1-16 
GsLINE (libgs), 1-17 
GsMAP (libgs), 1-18 
GsOBUTABLE? (libgs), 1-19 
GsOT (libgs), 1-20 
GsOT_TAG (libgs), 1-21 
GsRVIEW?2 (libgs), 1-22 
GsRVIEWUNIT (libhmd), 1-14 
GsSEH (ibhmo), 1-15 
GsSEQ (libhmd), 1-16 
GsSPRITE (libgs), 1-23 
GsTYPEUNIT (libhmd), 1-18 
GsUNIT (llbhmad), 1-20 
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LINE_F2, LINE_F8, LINE_F4 (libgpu), 1-16 
LINE_G2, LINE_G3, LINE_G4 (libgpu), 1-17 





M 
MATRIX (lipgte), 8-12 
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POLS (libgte), 8-13 

POL4 (libgte), 8-14 

POLY_F8, POLY_F4 (libgpu), 1-19 
POLY_FT8, POLY_FT4 (lilbgpu), 1-20 
POLY_G3, POLY_G4 (libgpu), 1-22 
POLY_GT8, POLY_GT4 (libgpu), 1-23 
ProgAtr (libsnd), 14-5 





Q 
QMESH (libgte), 8-15 


R 

RECT (lipbgpu), 1-25 
RECT32 (libgpu), 1-26 
RVECTOR (libgte), 8-16 





S 


SndRegisterAttr (libsnd), 14-6 
SndVoiceStats (libsnd), 14-7 
SndVolume (libsnd), 14-8 
SndVolume2 (libsnd), 14-9 
SPOL (libgte), 8-17 

SPRT (libgpu), 1-27 

SPRT_8, SPRT_16 (libgpu), 1-28 
SpuCommonAttr (libspu), 15-5 
SpuDecodeData (libspu), 15-6 
SpuEnv (libspu), 15-7 
SpuExtAttr (libspu), 15-8 
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SpuLVoiceAttr (libspu), 15-9 
SpuReverbAttr (libspu), 15-10 
SpuStEnv (libspu), 15-11 
SpuStVoiceAttr (libspu), 15-12 
SpuVoiceAttr (lipspu), 15-13 
SpuVolume (lipspu), 15-14 
StHEADER (lipcd), 10-7 
SVECTOR (libgte), 8-18 
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4 XXX Library Functions 


format (libapi), 1-29 
free (libc/libc2), 2-12 
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frexp (libmath), 3-15 
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GetODE (libgpu), 1-67 
GetRCnt (libapi), 1-35 

gets (libc/libc2), 2-15 

GetSp (libapi), 1-36 
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GsDefDispBuff (libgs), 1-39 
GsDefDispBuff2 (libgs), 1-40 
GsDrawOt (libgs), 1-41 
GsDrawoOltlo (lipgs), 1-42 
GsGetActiveBuffer (libgs), 1-43 
GsGetHeadpUnit (libhmd), 1-23 
GsGeltLs (libgs), 1-44 
GsGetLsUnit (liphmd), 1-24 
GsGetLw (libgs), 1-45 
GsGetLws (libgs), 1-46 
GsGetLwsUnit (libhmd), 1-25 
GsGetLwUnit (libhmd), 1-26 
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GsScanAnim (libhmd), 1-32 
GsScanunit (libhma), 1-33 
GsSetAmbient (libgs), 1-67 
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GsSetFlatLight (libgs), 1-73 
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GsSetRefViewUnit (libhma), 1-35 
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GsTMDfast... (libgs), 1-104 
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GsU_... (libhmd), 1-38 
GsU_03000000 (libhmd), 1-39 
GsU_03000001... (libhmd), 1-41 
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memset (libc/lioc2), 2-24 
modf (libmath), 3-20 
Movelmage (libgpu), 1-84 
Movelmage2 (libgpu), 1-85 
MulMattrix (libgte), 8-69 
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open (libapi), 1-53 
OpenEvent (libapi), 1-54 
Openth (libapi), 1-55 
OpenTIM (libgpu), 1-87 
OpenTMD (libgpu), 1-88 
otz2p (libgte), 8-81 
OuterProducto (libgte), 8-82 
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puts (libc/libc2), 2-28 
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RotTransPers3_nom (libgte), 8-143 
RotTransPers3N (lipgte), 8-144 
RotTransPers4 (libgte), 8-145 
RotTransPers4_nom (libgte), 8-146 
RotTransPersN (libgte), 8-147 
RotTransSv (lipgte), 8-148 

rsin (libgte), 8-149 








S 


ScaleMatrix (libgte), 8-150 

ScaleMatrixL (lipgte), 8-151 

SelectGUN (libgun), 12-35 
SetBackColor (libgte), 8-152 
SetColorMatrix (libgte), 8-153 

SetConf (libapi), 1-62 

SetDefDispEnv (libgpu), 1-94 
SetDefDrawEnv (libgpu), 1-95 
SetDispMask (libgpu), 1-96 
SetDrawArea (libgpu), 1-97 

SetDrawEnv (libgpu), 1-98 
SetDrawLoad (libgpu), 1-99 
SetDrawMode (libgpu), 1-100 
SetDrawMove (libgpu), 1-101 
SetDrawOffset (libgpu), 1-102 
SetDrawSip (libgpu), 1-103 
SetDrawTPage (libgpu), 1-104 
SetDumpFnt (libgpu), 1-105 
SetFarColor (libgte), 8-154 

SetFogFar (libgte), 8-155 

SetFogNear (libgte), 8-156 
SetFogNearFar (libgte), 8-157 
SetGeomOffset (libgte), 8-158 
SetGeomScreen (libgte), 8-159 
SetGraphDebug (libgpu), 1-106 

setimp (libc/libc2), 2-32 

SetLightMatrix (libgte), 8-160 

SetLineF2, SetLineF3, SetLineF4 (libgpu), 1-107 
SetLineG2, SetLineG3, SetLineG4 (libgpu), 1-107 
SetMem (libapi), 1-63 

SetMulMatrix (lipgte), 8-161 
SetMulRotMatrix (libgte), 8-162 
SetPolyF3, SetPolyF4 (lipgpu), 1-108 
SetPolyG3, SetPolyG4 (libgpu), 1-108 
SetPolyGT8, SetPolyGT4 (libgpu), 1-108 
SetRCnt (libapi), 1-64 

SetRGBcd (lipgte), 8-163 

SetRotMatrix (libgte), 8-164 
SetSemiTrans (libgpu), 1-109 
SetShadeTex (libgpu), 1-110 

SetSp (libapi), 1-65 

SetSprt, SetSprt8, SetSprt16 (libgpu), 1-111 
SetTexWindow (libgpu), 1-112 

SetTile, SetTile1, SetTile8, SetTile16 (libgpu), 1-113 
SetTransMatrix (libgte), 8-165 
SetVideoMode (libetc), 12-36 

sin (libmath), 3-23 

sinh (lilbmath), 3-24 

Sio1Callback (libsio), 16-5 

sprintf (libc/libc2), 2-33 

sprintf2 (libmath), 3-25 
SpuClearReverbWorkArea (lipspu), 15-15 

















SpuFlush (lipspu), 15-16 

SpuF ree (libspu), 15-17 

SpuGetAllKeysStatus (lipspu), 15-18 
SpuGetCommonAttr (libspu), 15-19 
SpuGetCommonCDMix (libspu), 15-20 
SpuGetCommonCDReverb (lipspu), 15-21 
SpuGetCommonCDVolume (libspu), 15-22 
SpuGetCommonMasterVolume (libspu), 15-23 
SpuGetCommonMasterVolumeAttr (libspu), 15-24 
SpuGetCommonMasterVolumex (libspu), 15-25 
SpuGetIRQ (libspu), 15-26 

SpuGetIRQAdadr (libspu), 15-27 

SpuGetKeyStatus (lipspu), 15-28 

SpuGetMute (lipspu), 15-29 

SpuGetNoiseClock (lipspu), 15-30 
SpuGetNoiseVoice (lipspu), 15-31 
SpuGetPitchLFOVoice (libspu), 15-32 
SpuGetReverb (lipspu), 15-33 
SpuGetReverbModeDelayTime (libspu), 15-34 
SpuGetReverbModeDepth (libspu), 15-35 
SpuGetReverbModeFeedback (lipspu), 15-36 
SpuGetReverbModeParam (libspu), 15-37 
SpuGetReverbModeType (lipspu), 15-38 
SpuGetReverbVoice (libspu), 15-39 
SpuGetTransferMode (lipspu), 15-40 
SpuGetTransferStartAdar (libspu), 15-41 
SpuGetVoiceADSR (libspu), 15-42 
SpuGetVoiceADSRAttr (libspu), 15-43 
SpuGetVoiceAR (lipspu), 15-44 
SpuGetVoiceARAttr (libspu), 15-45 
SpuGetVoiceAttr (libspu), 15-46 
SpuGetVoiceDR (libspu), 15-47 
SpuGetVoiceEnvelope (libspu), 15-48 
SpuGetVoiceEnvelopeAttr (libspu), 15-49 
SpuGetVoiceLoopStartAddr (libspu), 15-50 
SpuGetVoiceNote (libspu), 15-51 
SpuGetVoicePitch (libspu), 15-52 
SpuGetVoiceRR (lipspu), 15-53 
SpuGetVoiceRRAttr (libspu), 15-54 
SpuGetVoiceSampleNote (lipspu), 15-55 
SpuGetVoiceSL (libspu), 15-56 

SpuGetVoiceShR (libspu), 15-57 
SpuGetVoiceSRAttr (lipspu), 15-58 
SpuGetVoiceStartAdar (libspu), 15-59 
SpuGetVoiceVolume (liospu), 15-60 
SpuGetVoiceVolumeAttr (libspu), 15-61 
SpuGetVoiceVolumex (libspu), 15-62 

Spulnit (lipspu), 15-63 

SpulnitHot (libspu), 15-64 

SpulnitMalloc (lipspu), 15-65 
SpulsReverbWorkAreaReserved (lipspu), 15-66 
SpulsTransferCompleted (libspu), 15-67 
SpuLSetVoiceAttr (lipspu), 15-68 

SpuMalloc (libspu), 15-69 
SpuMallocWithStartAdar (lipspu), 15-70 
SpuNGetVoiceAttr (libspu), 15-71 
SpuNSetVoiceAttr (libspu), 15-72 

SpuQuit (libspu), 15-73 

SpuRead (lipspu), 15-74 

SpuReadDecodedData (libspu), 15-75 
SpuReserveReverbWorkArea (lipspu), 15-76 
SpuRGetAllKeysStatus (lipspu), 15-77 
SpuRSetVoiceAttr (libspu), 15-78 
SpuSetCommonaAttr (libspu), 15-79 
SpuSetCommonCDMixx (libspu), 15-80 
SpuSetCommonCDReverb (libspu), 15-81 
SpuSetCommonCDVolume (lipspu), 15-82 
SpuSetCommonMasterVolume (libspu), 15-83 
SpuSetCommonMasterVolumeAttr (lipspu), 15-84 
SpuSetEnv (libspu), 15-85 

SpuSetESA (libspu), 15-86 
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SpuSetIRQ (libspu), 15-87 
SpuSetIRQAddr (libspu), 15-88 
SpuSetIRQCallback (libspu), 15-89 
SpuSetKey (libspu), 15-90 
SpuSetKeyOnWithAttr (lilbspu), 15-91 
SpuSetMute (libspu), 15-92 
SpuSetNoiseClock (lipspu), 15-93 
SpuSetNoiseVoice (libspu), 15-94 
SpuSetPitchLFOVoice (lipspu), 15-95 
SpuSetReverh (libspu), 15-96 
SpuSetReverbDepth (libspu), 15-97 
SpuSetReverbModeDelayTime (libspu), 15-98 
SpuSetReverbModeDepth (lipbspu), 15-99 
SpuSetReverbModeFeedback (libspu), 15-100 
SpuSetReverbModeParam (libspu), 15-101 
SpuSetReverbModeType (lipspu), 15-103 
SpuSetReverbVoice (libspu), 15-104 
SpuSetTransferCallback (lipbspu), 15-105 
SpuSetTransferMode (lipspu), 15-106 
SpuSetTransferStartAdar (lipspu), 15-107 
SpuSetVoiceADSR (lipspu), 15-108 
SpuSetVoiceADSRAttr (libspu), 15-109 
SpuSetVoiceAR (libspu), 15-110 
SpuSetVoiceARAttr (libspu), 15-111 
SpuSetVoiceAttr (lipspu), 15-112 
SpuSetVoiceDR (lipspu), 15-115 
SpuSetVoiceLoopStartAdadr (libspu), 15-116 
SpuSetVoiceNote (libspu), 15-117 
SpuSetVoicePitch (libspu), 15-118 
SpuSetVoiceRR (lipbspu), 15-119 
SpuSetVoiceRRAttr (libspu), 15-120 
SpuSetVoiceSampleNote (lipspu), 15-121 
SpuSetVoiceSL (libspu), 15-122 
SpuSetVoiceSR (lipspu), 15-123 
SpuSetVoiceSRAttr (libspu), 15-124 
SpuSetVoiceStartAdadr (libspu), 15-125 
SpuSetVoiceVolume (libspu), 15-126 
SpuSetVoiceVolumeAttr (libspu), 15-127 
SpuStart (libspu), 15-128 

SpuStGetStatus (libspu), 15-129 
SpuStGetVoiceStatus (libspu), 15-130 
SpuStlnit (libspu), 15-131 

SpuStQuit (libspu), 15-132 
SpuStSetPreparationFinishedCallback (libspu), 15-133 
SpuStSetStreamFinishedCallback (libspu), 15-134 
SpuStSetTransferFinishedCallback (libspu), 15-135 
SpuStTransfer (libspu), 15-136 

SpuWrite (libspu), 15-137 

SpuWriteO (libspu), 15-138 

SpuWritePartly (libspu), 15-139 

sqrt (libmath), 3-26 

Square SLO (libgte), 8-170 

Square SL12 (libgte), 8-171 

Square SSO (libgte), 8-172 

Square SS12 (libgte), 8-173 

Square0 (libgte), 8-166 

Square12 (libgte), 8-167 

SquareRoot0 (libgte), 8-168 
SquareRoot1 2 (libgte), 8-169 

srand (lipc/lipc2), 2-34 

SsAllocateVoices (lipsnd), 14-15 
SsBlockVoiceAllocation (libsnd), 14-16 
SsChannelMute (lipsnd), 14-17 

SsEnd (lipsnd), 14-18 
SsGetActualProgFromProg (lipsnd), 14-19 
SsGetChannelMute (lipsnd), 14-20 
SsGetCurrentPoint (libsnd), 14-21 
SsGetMute (liosnd), 14-22 

SsGetMVol (libsnd), 14-23 

SsGetNck (libsnd), 14-24 

SsGetRVol (lipsnd), 14-25 
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SsGetSerialAttr (lipsnd), 14-26 
SsGetSerialVol (lipsnd), 14-27 
SsGetVoiceMask (libsnd), 14-28 
Sslnit (lilpsnd), 14-29 

SslnitHot (libsnd), 14-30 

SslsEos (libsnd), 14-31 
SsPitchFromNote (lipsnd), 14-32 
SsPlayBack (libsnd), 14-33 
SsQueueKeyOn (libsnd), 14-34 
SsQueueRegisters (libsnd), 14-35 
SsQueueReverh (libsnd), 14-36 
SsQuit (libsnd), 14-37 
SsSepClose (lipsnd), 14-38 
SsSepOpen (lipsnd), 14-39 
SsSepOpenu (libsnd), 14-40 
SsSepPause (libsnd), 14-41 
SsSepPlay (libsnd), 14-4 
SsSepReplay (lipsnd), 14-43 
SsSepSetAccelerando (libsnd), 14-44 
SsSepSetCrescendo (lipsnd), 14-45 
SsSepSetDecrescendo (libsnd), 14-46 
SsSepSetRitardando (libsnd), 14-47 
SsSepSetVol (liosnd), 14-48 
SsSepStop (libsnd), 14-49 
SsSeqCalledTbyT (libsnd), 14-50 
SsSeqClose (lipsnd), 14-51 
SsSeqGetVol (lipsnd), 14-52 
SsSeqOpen (lipsnd), 14-53 
SsSeqOpenu (libsnd), 14-54 
SsSeqPause (libsnd), 14-55 
SsSeaqPlay (libsnd), 14-56 
SsSeqPlayPtoP, 14-57 

SsSeqReplay (lipsnd), 14-58 
SsSeqSetAccelerando (libsnd), 14-59 
SsSeqSetCrescendo (lipsnd), 14-60 
SsSeqSetDecrescendo (libsnd), 14-61 
SsSeqSetNext (liosnd), 14-62 
SsSeqSetRitardando (libsnd), 14-63 
SsSeqSetVol (libsnd), 14-64 
SsSeqSkip, 14-65 

SsSeqStop (lipsnd), 14-66 
SsSetAutoKeyOffMode (lipsnd), 14-67 
SsSetCurrentPoint (libsnd), 14-68 
SsSetLoop (lipsnd), 14-69 
SsSetMarkCallback (libsnd), 14-70 
SsSetMono (lipbsnd), 14-71 

SsSetMute (libsnd), 14-72 

SsSetMVol (lipsnd), 14-73 

SsSetNck (lipsnd), 14-24 

SsSetNext (libsnd), 14-74 
SsSetNoiseOff (lipsnd), 14-24 
SsSetNoiseOn (lipsnd), 14-24 
SsSetReservedVoice (libsnd), 14-75 
SsSetRVol (libsnd), 14-76 
SsSetSerialAttr (libsnd), 14-77 
SsSetSerialVol (lipsnd), 14-78 
SsSetStereo (lipsnd), 14-79 
SsSetTableSize (lipsnd), 14-80 
SsSetTempo (lipsnd), 14-81 
SsSetTickCallBack (lipsnd), 14-82 
SsSetTickMode (lipsnd), 14-83 
SsSetVoiceMask (libsnd), 14-84 
SsSetVoiceSettings (libsnd), 14-85 
SsStart (libsnd), 14-86 

SsStart2 (lipsnd), 14-87 





N 
































SsUnBlockVoiceAllocation (libsnd), 14-88 


SsUtAllKeyOff (libsnd), 14-89 
SsUtAutoPan (libsnd), 14-90 
SsUtAutoVol (libsnd), 14-91 
SsUtChangeADSR (lipsnd), 14-92 
SsUtChangePitch (libsnd), 14-93 
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SsUtFlush (lipsnd), 14-94 
GetDetVVol (lipsnd), 14-95 
GetProgAtr (libsnd), 14-96 
GetReverbType (libsnd), 14-97 
GetVabHar (libsnd), 14-98 
GetVagAddr (libsnd), 14-99 


GetVagAtr (libsnd), 14-101 
GetVBaddrInSB (lipbsnd), 14-102 
GetVVol (libsnd), 14-103 

KeyOff (libsnd), 14-104 

KeyOffv (libsnd), 14-105 

KeyOn (libsnd), 14-106 

KeyOnV (libsnd), 14-107 
PitchBend (libsnd), 14-108 
ReverbOff (libsnd), 14-109 
ReverbOn (libsnd), 14-110 
SetDetVVol (libsnd), 14-111 
SsUtSetProgAtr (lipsnd), 14-112 
SsUtSetReverbDelay (libsnd), 14-113 
SsUtSetReverbDepth (libsnd), 14-114 
SsUtSetReverbFeedback (libsnd), 14-115 
SsUtSetReverbType (lipsna), 14-116 
SsUtSetVabHar (lipsnd), 14-117 
SsUtSetVagAtr (libsnd), 14-118 
SsUtSetVVol (libsnd), 14-119 
SsVabClose (lipsnd), 14-120 
SsVabFakeBody (libsnd), 14-121 
SsVabFakeHead (lipsnd), 14-122 
SsVabOpen (lipsnd), 14-123 
SsVabOpenHead (libsnd), 14-124 
SsVabOpenHeadSticky (libsnd), 14-125 
SsVabTransBody (libsnd), 14-126 
SsVabTransBodyPartly (lipsnd), 14-127 
SsVabTransCompleted (lipsnd), 14-128 
SsVabTransfer (libsnd), 14-129 
SsVoiceCheck (lipsnd), 14-130 
SsVoKeyOff (libsnd), 14-131 
SsVoKeyOn (lipsnd), 14-132 
StartCARD (libcard), 4-4 

artGUN (libgun), 12-37 

artPAD (libapi), 1-66 

artRCnt (libapi), 1-67 

artTAP (libtap), 12-38 

Cdlinterrupt (libcd), 10-45 

tClearRing (libcd), 10-46 

FreeRing (libcd), 10-47 

GetBackloc (libcd), 10-48 

GetNext (libcd), 10-49 

GetNextS (libcd), 10-50 

NextStatus (liocd), 10-51 
topCallback (libetc), 12-39 

OpCARD (libcard), 4-5 

OpGUN (libgun), 12-40 

OpPAD (libapi), 1-68 

opRCnt (libapi), 1-69 

OpTAP (libtap), 12-41 

orelmage (libgpu), 1-114 

orelmagez2 (libgpu), 1-115 

strcat (libc/libc2), 2-35 

rchr (libc/libc2), 2-36 

remp (libc/libc2), 2-37 

rcpy (libc/libc2), 2-38 

respn (libc/libc2), 2-39 

tRingStatus (libcd), 10-52 

rlen (libc/libc2), 2-40 

trncat (libc/lilbc2), 2-41 

rncmp (libc/libc2), 2-42 

rncpy (libc/lilbc2), 2-43 

rpbrk (libc/libc2), 2-44 

rrchr (lilbc/lilbc2), 2-45 
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GetVagAddrFromTone (libsnd), 14-100 


strspn (lipc/lipc2), 2-46 

strstr (lilbc/lilbc2), 2-47 

strtod (libc/libc2), 3-27 

strtok (libc/libc2), 2-48 

strtol (libc/libc2), 2-49 

strtoul (libc/libc2), 2-50 
StSetChannel (libcd), 10-53 
StSetEmulate (libcd), 10-54 
StSetMask (libcd), 10-55 
StSetRing (libcd), 10-56 
StSetStream (lipcd), 10-57 
StUnSetRing (libcd), 10-58 
SubPol (lipbgte), 8-174 

SubPol4 (lipbgte), 8-175 
SweEnterCriticalSection (libapi), 1-70 
SwExitCriticalSection (libapi), 1-71 
SystemError (libapi), 1-72 





T 


tan (libmath), 3-28 

tanh (libmath), 3-29 
TermPrim (libgpu), 1-116 
TestEvent (libapi), 1-73 


Macros 


A 


addPrim (libgpu), 1-33 
addPrims (libgpu), 1-34 
addVector (libgpu), 1-119 
applyVector (libgpu), 1-120 


Cc 


catPrim (libgpu), 1-36 
CombAsyncRequest (libcomb), 13-8 
CombBytesRemaining (libcomb), 13-9 
CombBytesToRead (libcomb), 13-10 
CombBytesToWrite (libcomb), 13-11 
CombCancelRead (libcomb), 13-12 
CombCancelWrite (libcomb), 13-13 
CombCortrolStatus (libcomb), 13-14 
CombCTS (libcomb), 13-15 
CombGetBPS (libcomb), 13-16 
CombGetMode (libcomb), 13-17 
CombGetPacketSize (libcomb), 13-18 
CombReset (libcomb), 13-19 
CombResetError (libcomb), 13-20 
CombResetVBLANK (libcomb), 13-21 
CombSetBPS (libcomb), 13-22 
CombSetControl (libcomb), 13-23 
CombSetMode (libcomb), 13-24 
CombSetPacketSize (libcomb), 13-25 
CombSetRTS (libcomb), 13-26 
CombSioStatus (libcomb), 13-27 
CombWaitCallback (libcomb), 13-28 
copyVector (libgpu), 1-121 





D 


dump... (libgpu), 1-125 
dumpClut (libgpu), 1-50 
dumpMatrix (libgpu), 1-122 
dumpRECT (lipbgpu), 1-123 
dumpTPage (libgpu), 1-54 
dumpVector (libgpu), 1-124 
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TransMatrix (lipgte), 8-176 
TransposeMatrix (libgte), 8-177 
TransRot_32 (lilbgte), 8-180 
TransRotPers (lipgte), 8-178 
TransRotPers3: (libgte), 8-179 


U 


undelete (libapi), 1-74 
UnDeliverEvent (libapi), 1-75 


Vv 


VectorNormal (lipbgte), 8-181 
VectorNormalS (libgte), 8-182 
VectorNormalSS (libgte), 8-183 
VSync (libetc), 1-117 
VSyncCallback (libetc), 1-118 


Ww 


WaitEvent (libapi), 1-76 
write (libapi), 1-77 


F 
fabs (liomath), 3-12 


G 


getClut (libgpu), 1-59 
getTPage (libgpu), 1-70 
GsClearDispArea (lipgs), 1-109 
GslncFrame (libgs), 1-110 
GsSetAzwh (libgs), 1-111 


isendprim (libgpu), 1-71 
iSXXXX... (lilbc/lilbc2), 2-16 


N 
nextPrim (libgpu), 1-86 


S 


setClut (libgpu), 1-126 

setDrawTPage (libgpu), 1-104 

setLineF2, setLineF3, setLineF4 (libgpu), 1-107 
setLineG2, setLineG3, setLineG4 (libgpu), 1-107 
setPolyF3, setPolyF4 (libgpu), 1-108 

setPolyG8, setPolyGé4 (libgpu), 1-108 
setPolyGT3, setPolyGT4 (libgpu), 1-108 
setRECT (libgpu), 1-127 

setRGBO, setRGB1, setRGB2, setRGBS3 (libgpu), 1-128 
setSemiTrans (libgpu), 1-109 

setShadeTex (libgpu), 1-110 

setSprt, setSprt8, setSprt16 (libgpu), 1-111 
setTexWindow (libgpu), 1-112 

setTile, setTile1, setTile8, setTile16 (libgpu), 1-113 
setTPage (libgpu), 1-129 

setUVO, setUV3, setUV4 (libgpu), 1-130 
setUVWH (libgpu), 1-131 

setVector (libgpu), 1-132 

setWH (lipbgpu), 1-133 

setXYO, set XY2, setXY3, setXY4 (libgpu), 1-134 
setXYWH (libgpu), 1-135 
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10 XxX Library Functions 


T toascii (libc/libc2), 2-51 
are tolower (libc/libo2), 2-52 
termPrim (libgpu), 1-116 toupper (libc/libc2}, 2-53 
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